@hyperfrontend/features 0.1.0 → 0.2.0

package/cli/index.esm.js

@@ -1,27 +1,27 @@
 import { createError } from '../_dependencies/@hyperfrontend/immutable-api-utils/built-in-copy/error/index.esm.js';
 import { execFileSync } from 'node:child_process';
-import { tmpdir } from 'node:os';
 import { join, dirname, isAbsolute, resolve, normalize, sep, extname, relative } from 'node:path';
 import { build } from '../_dependencies/@hyperfrontend/builder/index.esm.js';
+import { isArray } from '../_dependencies/@hyperfrontend/immutable-api-utils/built-in-copy/array/index.esm.js';
 import { stringify } from '../_dependencies/@hyperfrontend/immutable-api-utils/built-in-copy/json/index.esm.js';
-import { exists, readJsonFile, createDirectory, removeDirectory, readFileBuffer, isFile } from '../_dependencies/@hyperfrontend/project-scope/core/fs/index.esm.js';
+import { exists, readJsonFile, createDirectory, removeDirectory, writeFileContent, readFileContent, readJsonFileIfExists, writeJsonFile, readFileBuffer, isFile } from '../_dependencies/@hyperfrontend/project-scope/core/fs/index.esm.js';
 import { createTree, commitChanges, Mode } from '../_dependencies/@hyperfrontend/project-scope/vfs/index.esm.js';
 import { format } from '../_dependencies/@hyperfrontend/versioning/semver/format/index.esm.js';
 import { parseVersionStrict } from '../_dependencies/@hyperfrontend/versioning/semver/parse/index.esm.js';
-import { isArray } from '../_dependencies/@hyperfrontend/immutable-api-utils/built-in-copy/array/index.esm.js';
 import { entries, freeze } from '../_dependencies/@hyperfrontend/immutable-api-utils/built-in-copy/object/index.esm.js';
 import '../_dependencies/@hyperfrontend/json-utils/index.esm.js';
-import { pathToFileURL } from 'node:url';
+import { pathToFileURL, fileURLToPath } from 'node:url';
 import { isInteger } from '../_dependencies/@hyperfrontend/immutable-api-utils/built-in-copy/number/index.esm.js';
 import { createServer } from 'node:http';
 import { promiseAll, createPromise } from '../_dependencies/@hyperfrontend/immutable-api-utils/built-in-copy/promise/index.esm.js';
 import { discoverEntryPoints } from '../_dependencies/@hyperfrontend/project-scope/heuristics/entry-points/index.esm.js';
 import { text, PromptResult, select } from '../_dependencies/@hyperfrontend/questions/index.esm.js';
 import { generateMetadata } from '../_shared/generators/metadata/generate-metadata/index.esm.js';
-import { toSourceLiteral } from '../_shared/generators/shell/source-literal/index.esm.js';
+import { quoteString, formatKey, toSourceLiteral } from '../_shared/generators/shell/source-literal/index.esm.js';
 import { FEATURE_CONFIG_BASENAME, DEV_CONFIG_BASENAME, discoverConfigFile } from '../_shared/cli/config/discover/index.esm.js';
 import { loadModuleFile } from '../_shared/cli/config/load-module/index.esm.js';
 import { EXIT_OK, EXIT_ERROR, EXIT_CANCELLED } from '../_shared/cli/exit-codes/index.esm.js';
+import { waitForShutdown } from '../_shared/shared/shutdown/index.esm.js';
 import { generateFeatureModule } from '../_shared/generators/feature/generate-feature-module/index.esm.js';
 import { insertFeatureImport } from '../_shared/cli/insert-marker/index.esm.js';
 import { promptFeatureName, promptContractPath, promptEntryFile } from '../_shared/cli/prompts/index.esm.js';
@@ -42,6 +42,7 @@ const STRING_FLAGS = {
 };
 /** Boolean flags mapped to their {@link CliFlags} key. */
 const BOOLEAN_FLAGS = {
+    '--allow-open': 'allowOpen',
     '--ci': 'ci',
     '--yes': 'yes',
     '--dry-run': 'dryRun',
@@ -91,6 +92,7 @@ function parseCliArgs(argv) {
     }
     const flags = {
         ...strings,
+        allowOpen: booleans['allowOpen'] ?? false,
         ci: booleans['ci'] ?? false,
         yes: booleans['yes'] ?? false,
         dryRun: booleans['dryRun'] ?? false,
@@ -99,43 +101,357 @@ function parseCliArgs(argv) {
     return { ...(command !== undefined && { command }), flags };
 }
 
+// note: JSON-schema scalar types mapped straight to their TypeScript equivalents; `integer` narrows to `number`.
+const PRIMITIVES = {
+    string: 'string',
+    number: 'number',
+    integer: 'number',
+    boolean: 'boolean',
+    null: 'null',
+};
+/**
+ * Narrows an unknown value to a plain record.
+ *
+ * @param value - The value to test.
+ * @returns `true` when the value is a non-null, non-array object.
+ */
+function isRecord$3(value) {
+    return typeof value === 'object' && value !== null && !isArray(value);
+}
+/**
+ * Renders a JSON scalar as a TypeScript literal type.
+ *
+ * @param value - The candidate literal.
+ * @returns The literal type source, or `null` for a non-scalar value.
+ */
+function literalType(value) {
+    if (value === null) {
+        return 'null';
+    }
+    if (typeof value === 'string') {
+        return quoteString(value);
+    }
+    if (typeof value === 'number' || typeof value === 'boolean') {
+        return stringify(value);
+    }
+    return null;
+}
+/**
+ * Renders an `enum` member list as a union of literal types.
+ *
+ * @param members - The allowed values listed by the schema.
+ * @returns The union source, or `unknown` when any member is not a scalar.
+ */
+function enumType(members) {
+    const literals = members.map(literalType);
+    // why: One non-scalar member would poison the union with `unknown`, which silently absorbs the useful literals — better to fall back for the whole enum.
+    return literals.every((literal) => literal !== null) ? literals.join(' | ') : 'unknown';
+}
+/**
+ * Renders an `object` schema as an inline type literal.
+ *
+ * @param schema - The schema record with optional `properties` and `required`.
+ * @param indent - The current indentation prefix.
+ * @returns The object type source; `Record<string, unknown>` without properties.
+ */
+function objectType(schema, indent) {
+    const properties = isRecord$3(schema['properties']) ? entries(schema['properties']) : [];
+    if (properties.length === 0) {
+        return 'Record<string, unknown>';
+    }
+    const required = isArray(schema['required']) ? schema['required'] : [];
+    const inner = `${indent}  `;
+    const members = properties.map(([key, member]) => `${inner}${formatKey(key)}${required.includes(key) ? '' : '?'}: ${schemaToType(member, inner)}`);
+    return `{\n${members.join('\n')}\n${indent}}`;
+}
+/**
+ * Renders an `array` schema as an element-type array.
+ *
+ * @param schema - The schema record with an optional single `items` schema.
+ * @param indent - The current indentation prefix.
+ * @returns The array type source; `unknown[]` without a single `items` schema.
+ */
+function arrayType(schema, indent) {
+    const items = schema['items'];
+    if (!isRecord$3(items)) {
+        return 'unknown[]';
+    }
+    const element = schemaToType(items, indent);
+    return element.includes('|') ? `(${element})[]` : `${element}[]`;
+}
+/**
+ * Projects a JSON-schema-like payload description into TypeScript type source.
+ *
+ * Bounded mapping: scalar `type`s, `object` with `properties`/`required`,
+ * `array` with a single `items` schema, `enum`, and `const` are projected;
+ * anything else (including a missing schema) falls back to `unknown`, so a
+ * generated type is never wrong — at worst it is loose.
+ *
+ * @param schema - The schema value to project.
+ * @param indent - Indentation prefix applied to nested object members.
+ * @returns The TypeScript type as source text.
+ *
+ * @example Projecting an action payload schema
+ * ```typescript
+ * schemaToType({ type: 'object', properties: { tz: { type: 'string' } }, required: ['tz'] })
+ * // => '{\n  tz: string\n}'
+ * ```
+ */
+function schemaToType(schema, indent = '') {
+    if (!isRecord$3(schema)) {
+        return 'unknown';
+    }
+    const enumMembers = schema['enum'];
+    if (isArray(enumMembers) && enumMembers.length > 0) {
+        return enumType(enumMembers);
+    }
+    if ('const' in schema) {
+        return literalType(schema['const']) ?? 'unknown';
+    }
+    const type = schema['type'];
+    if (typeof type !== 'string') {
+        return 'unknown';
+    }
+    const primitive = PRIMITIVES[type];
+    if (primitive !== undefined) {
+        return primitive;
+    }
+    if (type === 'object') {
+        return objectType(schema, indent);
+    }
+    if (type === 'array') {
+        return arrayType(schema, indent);
+    }
+    return 'unknown';
+}
+
+// note: The generated declarations are structural (no type imports from the SDK), so the connector's d.ts stays fully usable for consumers who install nothing but the packed tarball.
+const STATIC_TYPES = `/** How the feature is surfaced by the host. */
+export type FeatureDisplayMode = 'embedded' | 'dialog' | 'popup' | 'standalone'
+
+/** Security envelope selector negotiated between host and feature. */
+export type FeatureSecurityProtocol = 'none' | 'v1' | 'v2'
+
+/** Context handed to an experience plugin around the feature's mount lifecycle. */
+export interface FeaturePluginContext {
+  /** In-document root the display mode mounted, or \`null\` for windowed modes. */
+  element: HTMLElement | null
+  /** The display mode the feature was surfaced in. */
+  displayMode: FeatureDisplayMode
+}
+
+/** Opt-in extension that decorates the feature's mount lifecycle (e.g. transitions). */
+export interface FeatureExperiencePlugin {
+  /** Unique plugin name, surfaced in debug logs. */
+  name: string
+  /**
+   * Runs after the feature mounts; may animate it in and return a teardown.
+   *
+   * @param context - The mounted element and its display mode.
+   * @returns An optional teardown invoked on unmount.
+   */
+  onMount?(context: FeaturePluginContext): void | (() => void)
+  /**
+   * Runs before the feature unmounts; may defer teardown until an exit animation finishes.
+   *
+   * @param context - The mounted element and its display mode.
+   * @returns Optionally a promise the shell awaits before tearing down.
+   */
+  onUnmount?(context: FeaturePluginContext): void | Promise<void>
+}
+
+/** Details handed to an unresponsive-feature callback when the feature stops responding. */
+export interface FeatureUnresponsiveInfo {
+  /** Consecutive missed heartbeats that tripped the watchdog. */
+  missedBeats: number
+  /** Timestamp (ms) of the last heartbeat received, or \`null\` if none ever arrived. */
+  lastBeatAt: number | null
+  /** The display mode the unresponsive feature was using. */
+  displayMode: FeatureDisplayMode
+  /** Closes the feature gracefully. */
+  close(): void
+  /** Closes the feature and releases all resources. */
+  destroy(): void
+}
+
+/**
+ * Options accepted by \`createFeatureShell\`; anything omitted falls back to the
+ * defaults baked in from the feature's build.
+ */
+export interface FeatureShellOptions {
+  /** Target element (or CSS selector) the embedded feature mounts into. */
+  container: string | HTMLElement
+  /** Stable identifier for the feature; seeds the broker name surfaced in debug logs. */
+  name?: string
+  /** How the feature should be surfaced; defaults to \`embedded\`. */
+  displayMode?: FeatureDisplayMode
+  /** URL of the feature app to load; defaults to the URL baked in from the feature config. */
+  url?: string
+  /** How an embedded feature is sized; defaults to \`fill\` (the iframe fills its container). */
+  embedSizing?: 'fill' | 'content'
+  /** How the host reacts when the feature stops responding; defaults to \`emit\`. */
+  onUnresponsive?: 'emit' | 'unmount' | ((info: FeatureUnresponsiveInfo) => void)
+  /** Whether pressing Escape closes the shell; defaults to \`true\`. */
+  closeOnEscape?: boolean
+  /** Dialog width in pixels (dialog mode only). */
+  dialogWidth?: number
+  /** Dialog height in pixels (dialog mode only). */
+  dialogHeight?: number
+  /** Whether the dialog renders a dimmed backdrop; defaults to \`true\`. */
+  dialogOverlay?: boolean
+  /** Security envelope to negotiate; defaults to the protocol baked in from the feature's build. */
+  protocol?: FeatureSecurityProtocol
+  /** Pre-shared key used by the \`v2\` protocol; always supplied by the host, never baked into the connector. */
+  sharedKey?: string
+  /** Experience plugins wrapped around each mount/unmount. */
+  plugins?: readonly FeatureExperiencePlugin[]
+}
+
+/** Handle returned by \`createFeatureShell\`, narrowed to the feature's contract. */
+export interface FeatureShellHandle {
+  /**
+   * Mounts the feature using the merged baked defaults and call-time options.
+   *
+   * @param options - Per-open overrides layered over the baked and create-time options.
+   */
+  open(options?: Partial<FeatureShellOptions>): void
+  /** Closes the feature gracefully, disconnecting the messaging channel. */
+  close(): void
+  /** Closes the feature and releases all resources (channel and DOM). */
+  destroy(): void
+  /**
+   * Sends a contract action to the feature.
+   *
+   * @param type - Action type from the feature contract's accepted list.
+   * @param data - Payload matching the action's schema.
+   */
+  send<T extends HostSendType>(type: T, data?: HostSendPayloads[T]): void
+  /**
+   * Subscribes to a feature event with its contract-typed payload.
+   *
+   * @param event - Event type from the feature contract's emitted list.
+   * @param handler - Callback invoked with the typed event payload.
+   * @returns A function that removes this subscription.
+   */
+  on<T extends HostEventType>(event: T, handler: (data: HostEventPayloads[T]) => void): () => void
+  /**
+   * Subscribes to a shell lifecycle event.
+   *
+   * @param event - Lifecycle event name.
+   * @param handler - Callback invoked when the event fires.
+   * @returns A function that removes this subscription.
+   */
+  on(event: 'open' | 'close' | 'error', handler: (data?: unknown) => void): () => void
+  /** Whether the feature channel is currently open (\`true\` while connected). */
+  readonly isOpen: boolean
+}
+`;
+/**
+ * Escapes a contract description for safe embedding inside a JSDoc comment.
+ *
+ * @param description - The raw description text.
+ * @returns The text with any comment terminator defused.
+ */
+function escapeDoc(description) {
+    return description.split('*/').join('*\\/');
+}
+/**
+ * Renders one payload-map member for an action, with its description as JSDoc.
+ *
+ * @param action - The contract action to render.
+ * @returns The interface member source.
+ */
+function buildMember(action) {
+    const doc = action.description === undefined ? '' : `  /** ${escapeDoc(action.description)} */\n`;
+    return `${doc}  ${formatKey(action.type)}: ${schemaToType(action.schema, '  ')}`;
+}
+/**
+ * Renders a payload-map interface keyed by action type.
+ *
+ * @param name - The interface identifier.
+ * @param doc - The single-line JSDoc summary.
+ * @param actions - The contract actions projected into members.
+ * @returns The interface declaration source.
+ */
+function buildPayloadInterface(name, doc, actions) {
+    const body = actions.length === 0 ? '' : `\n${actions.map(buildMember).join('\n')}\n`;
+    return `/** ${doc} */\nexport interface ${name} {${body}}`;
+}
+/**
+ * Builds the connector's full generated type surface for a feature contract.
+ *
+ * Emits payload maps and literal action-name unions projected from the
+ * contract, plus structural shell option and handle types, so the connector's
+ * declarations resolve with no dependencies beyond the DOM lib.
+ *
+ * @param contract - The feature contract driving the projected types.
+ * @returns The type declaration block for the connector entry.
+ *
+ * @example Projecting the clock contract
+ * ```typescript
+ * buildConnectorTypes({ emitted: [{ type: 'timeUpdated' }], accepted: [{ type: 'setTimezone' }] })
+ * // => source containing "export interface HostSendPayloads { setTimezone: unknown }"
+ * ```
+ */
+function buildConnectorTypes(contract) {
+    return `${buildPayloadInterface('HostSendPayloads', 'Payloads for actions the host can send, keyed by action type from the feature contract.', contract.accepted)}
+
+${buildPayloadInterface('HostEventPayloads', 'Payloads for events the feature emits to the host, keyed by event type from the feature contract.', contract.emitted)}
+
+/** Action types the host can send to the feature. */
+export type HostSendType = keyof HostSendPayloads
+
+/** Event types the feature emits to the host. */
+export type HostEventType = keyof HostEventPayloads
+
+${STATIC_TYPES}`;
+}
+
 const ENTRY_PATH = 'src/index.ts';
 const PACKAGE_PATH = 'package.json';
 const README_PATH = 'README.md';
 /**
  * Builds the baked-in default shell options from the resolved config.
  *
- * @param config - The resolved feature config supplying the URL and display defaults.
+ * @param config - The resolved feature config supplying the URL, protocol, and display defaults.
  * @returns A record of options the connector merges under host-supplied overrides.
  */
 function buildDefaults(config) {
-    return { url: config.url, ...(config.display ?? {}) };
+    return {
+        url: config.url,
+        ...(config.protocol !== undefined && { protocol: config.protocol }),
+        ...(config.display ?? {}),
+    };
 }
 /**
- * Builds the connector's TypeScript entry source with the contract inlined.
+ * Builds the connector's TypeScript entry source with the contract inlined and
+ * the contract-projected types exported.
  *
  * @param config - The resolved feature config naming the feature and its URL.
  * @param contract - The validated contract inlined into the connector.
  * @returns The entry module source as a string.
  */
 function buildConnectorEntry(config, contract) {
-    return `import type { ShellHandle, ShellOptions } from '@hyperfrontend/features/host'
-import { createShell } from '@hyperfrontend/features/host'
+    return `import { createShell } from '@hyperfrontend/features/host'
 
-/** Inlined contract describing the ${config.name} feature's actions. */
+${buildConnectorTypes(contract)}
+/** Inlined contract describing the ${config.name} feature's actions, exactly as the feature authored it. */
 const contract = ${toSourceLiteral(contract)}
 
-/** Default shell options baked in from the feature config. */
-const defaults = ${toSourceLiteral(buildDefaults(config))}
+/** Default shell options baked in from the feature's build. */
+const defaults = <const>${toSourceLiteral(buildDefaults(config))}
 
 /**
  * Creates a host-side shell for the ${config.name} feature.
  *
+ * The feature's contract and build-time defaults are baked in, and \`send\`/\`on\`
+ * are typed from the contract's actions.
+ *
  * @param options - Host-supplied options (at minimum a \`container\`); these override the baked defaults.
- * @returns A shell handle exposing \`open\`, \`close\`, \`destroy\`, \`send\`, \`on\`, and \`isOpen\`.
+ * @returns A typed shell handle exposing \`open\`, \`close\`, \`destroy\`, \`send\`, \`on\`, and \`isOpen\`.
  */
-export function createFeatureShell(options: ShellOptions): ShellHandle {
-  return createShell({ ...defaults, ...options, contract })
+export function createFeatureShell(options: FeatureShellOptions): FeatureShellHandle {
+  return <FeatureShellHandle>createShell({ ...defaults, ...options, contract })
 }
 `;
 }
@@ -158,49 +474,108 @@ function buildConnectorPackageJson(config) {
     };
     return `${stringify(manifest, null, 2)}\n`;
 }
+/**
+ * Builds the open-connector warning block for a protocol-`none` build.
+ *
+ * @param config - The resolved feature config carrying the baked protocol.
+ * @returns The warning block, or an empty string for secured builds.
+ */
+function buildReadmeWarning(config) {
+    if (config.protocol !== 'none') {
+        return '';
+    }
+    return `> **Warning: open connector.** This build uses protocol \`none\`: messages between host and feature travel with no security envelope, so any page that can reach the feature URL can embed and drive it. For production, rebuild the feature with \`--protocol v1\` or \`--protocol v2\`.
+
+`;
+}
+/**
+ * Builds the security paragraph matching the baked protocol.
+ *
+ * @param config - The resolved feature config carrying the baked protocol.
+ * @returns The security guidance paragraph.
+ */
+function buildReadmeSecurity(config) {
+    if (config.protocol === 'v2') {
+        return "The `v2` security envelope is baked in from the feature's build — do not pass `protocol` yourself. Supply your own pre-shared key via `sharedKey`; a key is never baked into the artifact.";
+    }
+    if (config.protocol === 'v1') {
+        return "The `v1` security envelope is baked in from the feature's build — do not pass `protocol` yourself.";
+    }
+    if (config.protocol === 'none') {
+        return 'This connector was deliberately built open (see the warning above); harden it by rebuilding the feature with a security protocol.';
+    }
+    return "No security envelope is baked into this connector; pass `protocol: 'v1'` or `protocol: 'v2'` (with your own `sharedKey` for `v2`) when creating the shell.";
+}
+/**
+ * Builds the option lines shown inside the quick-start `createFeatureShell` call.
+ *
+ * @param config - The resolved feature config carrying the baked protocol.
+ * @returns Extra option lines, each newline-prefixed, or an empty string.
+ */
+function buildReadmeOptions(config) {
+    if (config.protocol === 'v2') {
+        return "\n  sharedKey: 'your-pre-shared-key',";
+    }
+    if (config.protocol === undefined) {
+        return "\n  protocol: 'v2',\n  sharedKey: 'your-pre-shared-key',";
+    }
+    return '';
+}
+/**
+ * Builds the typed messaging example lines from the contract's first actions.
+ *
+ * @param contract - The validated feature contract.
+ * @returns Messaging example lines ending in a newline, or an empty string.
+ */
+function buildReadmeMessaging(contract) {
+    const sent = contract.accepted[0];
+    const received = contract.emitted[0];
+    const sendLine = sent === undefined ? '' : `shell.send('${sent.type}', data)  // typed: the payload shape comes from the feature contract\n`;
+    const onLine = received === undefined ? '' : `shell.on('${received.type}', (data) => console.log(data))  // typed: data follows the contract\n`;
+    return `${sendLine}${onLine}`;
+}
 /**
  * Builds the connector's `README.md` documenting the generated install + usage.
  *
  * @param config - The resolved feature config naming the feature.
+ * @param contract - The validated feature contract driving the typed examples.
  * @returns The README contents as a string.
  */
-function buildConnectorReadme(config) {
+function buildConnectorReadme(config, contract) {
     return `# ${config.name}-shell
 
-Generated host connector for the **${config.name}** feature. Self-contained — install it and embed the feature with one call.
+Generated host connector for the **${config.name}** feature. Self-contained — install it and embed the feature with one call. \`send\` and \`on\` are typed from the feature's contract.
 
-\`\`\`typescript
+${buildReadmeWarning(config)}\`\`\`typescript
 import { createFeatureShell } from '${config.name}-shell'
 
 const shell = createFeatureShell({
-  container: '#${config.name}',
-  // Security envelope: 'none' (default) | 'v1' | 'v2'.
-  // 'v2' authenticates the channel with a pre-shared key.
-  protocol: 'v2',
-  sharedKey: 'your-pre-shared-key',
+  container: '#${config.name}',${buildReadmeOptions(config)}
 })
 
 // Lifecycle events ('open', 'close', 'error'); on() returns an unsubscribe fn.
 const unsubscribe = shell.on('open', () => console.log('connected'))
 
-shell.open()                              // mount the feature in its display mode
-shell.send('setTimezone', { tz: 'UTC' })  // send an action the feature accepts
-console.log(shell.isOpen)                 // current connection state
+shell.open()               // mount the feature in its display mode
+${buildReadmeMessaging(contract)}console.log(shell.isOpen)  // current connection state
 
 unsubscribe()
-shell.close()                             // disconnect gracefully
-shell.destroy()                           // disconnect and release all resources
+shell.close()              // disconnect gracefully
+shell.destroy()            // disconnect and release all resources
 \`\`\`
 
+${buildReadmeSecurity(config)}
+
 > Regenerated from scratch on every build; do not edit by hand.
 `;
 }
 /**
  * Stages the complete host connector package into the supplied VFS tree.
  *
- * Emits the entry source, source-level `package.json`, `README.md`, and (via
- * {@link generateMetadata}) `metadata.json`. Pure: stages only into `tree` — the
- * CLI owns temp-dir creation, bundling, and commit.
+ * Emits the entry source (with contract-projected types), source-level
+ * `package.json`, `README.md`, and (via {@link generateMetadata})
+ * `metadata.json`. Pure: stages only into `tree` — the CLI owns temp-dir
+ * creation, bundling, and commit.
  *
  * @param config - The resolved feature config.
  * @param contract - The validated feature contract, inlined into the connector.
@@ -208,13 +583,13 @@ shell.destroy()                           // disconnect and release all resource
  *
  * @example Staging a connector for the clock feature
  * ```typescript
- * generateShell({ name: 'clock', version: '1.0.0', contract: './clock.contract.json', url: '/clock' }, contract, tree)
+ * generateShell({ name: 'clock', version: '1.0.0', contract: './clock.contract.json', url: '/clock', protocol: 'v2' }, contract, tree)
  * ```
  */
 function generateShell(config, contract, tree) {
     tree.write(ENTRY_PATH, buildConnectorEntry(config, contract));
     tree.write(PACKAGE_PATH, buildConnectorPackageJson(config));
-    tree.write(README_PATH, buildConnectorReadme(config));
+    tree.write(README_PATH, buildConnectorReadme(config, contract));
     generateMetadata(config, contract, tree);
 }
 
@@ -251,6 +626,31 @@ function collectActionListIssues(actions, field, issues) {
         if (typeof action['type'] !== 'string' || action['type'].length === 0) {
             issues.push(`"${field}[${index}]" must have a non-empty string "type".`);
         }
+        if (action['respondsWith'] !== undefined && (typeof action['respondsWith'] !== 'string' || action['respondsWith'].length === 0)) {
+            issues.push(`"${field}[${index}]" has a "respondsWith" that must be a non-empty string.`);
+        }
+    });
+}
+/**
+ * Collects every `respondsWith` reference that does not name an action in the other direction.
+ *
+ * A request emitted by one side is answered by an action the same side accepts (and
+ * vice versa), so each `respondsWith` must resolve across the contract's directions.
+ *
+ * @param actions - The already well-formed action list to check.
+ * @param field - The field name of `actions`, used to locate problems in messages.
+ * @param other - The action list of the opposite direction.
+ * @param otherField - The field name of `other`, used in messages.
+ * @param issues - The running list of human-readable problems, appended to in place.
+ */
+function collectRespondsWithIssues(actions, field, other, otherField, issues) {
+    actions.forEach((action, index) => {
+        if (action.respondsWith === undefined) {
+            return;
+        }
+        if (!other.some((candidate) => candidate.type === action.respondsWith)) {
+            issues.push(`"${field}[${index}]" responds with "${action.respondsWith}", but "${otherField}" has no action of that type.`);
+        }
     });
 }
 /**
@@ -276,7 +676,7 @@ function describeType(value) {
  *
  * @param contract - The candidate contract, typically parsed from disk.
  * @returns The validated contract, typed.
- * @throws {Error} When the value is not an object, or any action is malformed.
+ * @throws {Error} When the value is not an object, any action is malformed, or a `respondsWith` names no action in the other direction.
  *
  * @example Validating a parsed contract file
  * ```typescript
@@ -291,6 +691,12 @@ function validateContract(contract) {
     const issues = [];
     collectActionListIssues(contract['emitted'], 'emitted', issues);
     collectActionListIssues(contract['accepted'], 'accepted', issues);
+    if (issues.length === 0) {
+        const emitted = contract['emitted'];
+        const accepted = contract['accepted'];
+        collectRespondsWithIssues(emitted, 'emitted', accepted, 'accepted', issues);
+        collectRespondsWithIssues(accepted, 'accepted', emitted, 'emitted', issues);
+    }
     if (issues.length > 0) {
         throw createError(`Invalid contract:\n${issues.map((issue) => `  - ${issue}`).join('\n')}`);
     }
@@ -351,7 +757,7 @@ function toAbsolute$3(base, path) {
  * replaces its whole top-level key (no deep merge).
  *
  * @param options - The working directory and parsed flags.
- * @returns The resolved config, loaded contract, protocol, and source path.
+ * @returns The resolved config, loaded contract, protocol (with its explicitness), and source path.
  * @throws {Error} When the config or contract is missing required keys or malformed.
  *
  * @example Resolving from a discovered config plus a flag override
@@ -372,7 +778,9 @@ async function resolveBuildConfig(options) {
         contract: flags.contract ?? loaded['contract'],
     };
     const config = validateFeatureConfig(merged);
-    const protocol = flags.protocol ?? loaded['protocol'] ?? 'none';
+    // why: An explicitly chosen protocol (flag or config) is distinguished from the fallback so the build gate can require a deliberate acknowledgment for an open build instead of ever defaulting into one.
+    const chosenProtocol = flags.protocol ?? loaded['protocol'];
+    const protocol = chosenProtocol ?? 'none';
     if (typeof protocol !== 'string' || !VALID_PROTOCOLS.includes(protocol)) {
         throw createError(`Invalid protocol: "${String(protocol)}" (expected none, v1, or v2).`);
     }
@@ -383,8 +791,15 @@ async function resolveBuildConfig(options) {
         ...config,
         url: flags.url ?? (typeof loaded['url'] === 'string' ? loaded['url'] : '/'),
         ...(display !== undefined && { display }),
+        protocol: protocol,
+    };
+    return {
+        config: resolved,
+        contract,
+        protocol: protocol,
+        protocolExplicit: chosenProtocol !== undefined,
+        ...(sourcePath !== null && { sourcePath }),
     };
-    return { config: resolved, contract, protocol: protocol, ...(sourcePath !== null && { sourcePath }) };
 }
 
 const DEFAULT_OUT = 'dist';
@@ -427,9 +842,12 @@ function defaultPackTarball(packageDir) {
     return output.trim().split('\n').pop() ?? '';
 }
 /**
- * Builds the connector: resolve config → generate the host connector into a temp
- * dir → bundle via the builder → pack a tarball into `--out`. A `v1`/`v2` security
- * protocol is required for production output, and the temp dir is always removed.
+ * Builds the connector: resolve config → generate the host connector into a
+ * hidden staging dir inside the project → bundle via the builder → pack a
+ * tarball into `--out`. A `v1`/`v2` security protocol is required for production
+ * output; an explicit `--protocol none` builds only when paired with
+ * `--allow-open`, acknowledging the open channel. The staging dir is always
+ * removed.
  *
  * @param options - Flags, working directory, output sinks, and injectable deps.
  * @returns The process exit code.
@@ -447,23 +865,34 @@ async function runBuild(options) {
     const packTarball = options.packTarball ?? defaultPackTarball;
     let tempDir = null;
     try {
-        const { config, contract, protocol } = await resolveConfig({ cwd, flags });
+        const { config, contract, protocol, protocolExplicit } = await resolveConfig({ cwd, flags });
         if (protocol === 'none') {
-            stderr.write('Build requires a security protocol: pass --protocol v1 or --protocol v2.\n');
-            return EXIT_ERROR;
+            if (!protocolExplicit) {
+                stderr.write('Build requires a security protocol: pass --protocol v1 or --protocol v2.\n');
+                return EXIT_ERROR;
+            }
+            if (flags.allowOpen !== true) {
+                stderr.write("Building with an explicit protocol 'none' produces an open connector: the channel is unauthenticated and any page can embed and message the feature. Pass --allow-open to acknowledge the risk, or pick --protocol v1 / --protocol v2.\n");
+                return EXIT_ERROR;
+            }
+            stderr.write("Warning: building an open connector (protocol 'none'); the channel carries no security envelope.\n");
         }
-        const out = toAbsolute$2(cwd, flags.out ?? DEFAULT_OUT);
+        // why: The default output nests per connector so the builder's clean step only ever empties this connector's own directory, never a shared dist/ root.
+        const out = toAbsolute$2(cwd, flags.out ?? join(DEFAULT_OUT, `${config.name}-shell`));
         if (flags.dryRun) {
             stdout.write(`Would build "${config.name}" → ${out} [dry run]\n`);
             return EXIT_OK;
         }
-        tempDir = join(tmpdir(), `hf-shell-${config.name.replace(/[^a-z0-9-]/gi, '-')}-${process.pid}`);
+        // why: The staging dir lives inside the consumer project (not the OS temp dir) so module resolution can ascend into the consumer's node_modules and bundle the SDK into a self-contained connector.
+        tempDir = join(cwd, `.hf-shell-${config.name.replace(/[^a-z0-9-]/gi, '-')}-${process.pid}`);
         createDirectory(tempDir, { recursive: true });
         const tree = createTree(tempDir);
         generateShell(config, contract, tree);
         tree.write('tsconfig.lib.json', buildTsConfig());
         commitChanges(tree);
-        await runBuilder({ projectRoot: tempDir, workspaceRoot: tempDir, outputPath: out });
+        // why: The consumer project is the workspace — it holds node_modules (so the SDK bundles in) and the TypeScript binary the declaration pass spawns.
+        await runBuilder({ projectRoot: tempDir, workspaceRoot: cwd, outputPath: out });
+        publishSidecars(tempDir, out);
         const tarball = packTarball(out);
         stdout.write(`Built "${config.name}" → ${out}\n${tarball ? `Packed ${tarball}\n` : ''}`);
         return EXIT_OK;
@@ -477,6 +906,23 @@ async function runBuild(options) {
             removeDirectory(tempDir, { recursive: true, force: true });
     }
 }
+/**
+ * Copies the staged consumer-facing sidecars (`README.md`, `metadata.json`)
+ * into the built package and lists the metadata file in the manifest's `files`
+ * array so `npm pack` ships them with the connector.
+ *
+ * @param tempDir - The staging directory holding the generated sidecars.
+ * @param out - The built package directory the tarball is packed from.
+ */
+function publishSidecars(tempDir, out) {
+    writeFileContent(join(out, 'README.md'), readFileContent(join(tempDir, 'README.md')));
+    writeFileContent(join(out, 'metadata.json'), readFileContent(join(tempDir, 'metadata.json')));
+    const manifestPath = join(out, 'package.json');
+    const manifest = readJsonFileIfExists(manifestPath);
+    if (manifest !== null && isArray(manifest['files'])) {
+        writeJsonFile(manifestPath, { ...manifest, files: [...manifest['files'], 'metadata.json'] });
+    }
+}
 /**
  * Builds the minimal `tsconfig.lib.json` the builder reads for declarations.
  *
@@ -488,6 +934,8 @@ function buildTsConfig() {
             target: 'ES2022',
             module: 'ESNext',
             moduleResolution: 'Bundler',
+            // why: An explicit rootDir anchors the compiler's file matching to the staged sources, keeping the build correct no matter which directory the CLI is invoked from.
+            rootDir: 'src',
             declaration: true,
             strict: true,
             skipLibCheck: true,
@@ -671,6 +1119,29 @@ async function resolveDevConfig(options) {
     };
 }
 
+/**
+ * Directory of the currently-running module under either module system.
+ *
+ * The CommonJS build (and any CommonJS host) exposes `__dirname`; the
+ * ES-module build derives the directory from `import.meta.url`. Both formats
+ * ship beside the `debug-ui` assets, so the result anchors asset
+ * self-location wherever the package is installed or embedded.
+ *
+ * @returns Absolute directory path of the running module.
+ *
+ * @example Anchoring an asset lookup beside the running module
+ * ```typescript
+ * const assetDir = join(currentModuleDir(), 'debug-ui')
+ * ```
+ */
+function currentModuleDir() {
+    // why: `typeof` guards the CommonJS-only global so the ES-module build falls through to `import.meta.url` instead of crashing on an undefined identifier.
+    if (typeof __dirname !== 'undefined') {
+        return __dirname;
+    }
+    return dirname(fileURLToPath(import.meta.url));
+}
+
 // note: Minimal MIME table for the asset types a compiled feature/debug-UI bundle ships; anything else falls back to octet-stream.
 const CONTENT_TYPES = freeze({
     '.html': 'text/html; charset=utf-8',
@@ -779,23 +1250,66 @@ function createStaticHandler(root, deps = {}) {
     return (req, res) => serveFile(root, req.url ?? '/', res, deps);
 }
 
-// note: Path prefix the control server serves the compiled debug-UI assets under; the page loads `/__debug/bootstrap.js`.
+// note: Path prefix the control server serves the compiled debug-UI assets under; the page loads `/__debug/index.iife.min.js`.
 const DEBUG_PREFIX = '/__debug';
 // note: Placeholder the debug-UI HTML embeds; the control server swaps it for the live JSON manifest at request time.
 const MANIFEST_TOKEN = 'HF_MANIFEST_PLACEHOLDER';
 /**
- * Resolves the directory the compiled debug-UI assets ship in, located beside
- * this module via `__dirname` so the server finds them wherever the package is
- * installed.
+ * Probes a single directory for the shipped debug-UI assets, checking both a
+ * sibling `debug-ui` folder (running from the `server/` output) and a nested
+ * `server/debug-ui` folder (running from another package entry, such as the
+ * CLI bin at the package root).
+ *
+ * @param dir - Candidate directory expected to hold the assets.
+ * @param isFile - File probe used to confirm the assets exist.
+ * @returns The `debug-ui` asset directory, or `undefined` when it is not here.
+ */
+function probeAssetDir(dir, isFile) {
+    const sibling = join(dir, 'debug-ui');
+    if (isFile(join(sibling, 'index.html'))) {
+        return sibling;
+    }
+    const nested = join(dir, 'server', 'debug-ui');
+    return isFile(join(nested, 'index.html')) ? nested : undefined;
+}
+/**
+ * Locates the debug-UI assets by ascending from a start directory toward the
+ * filesystem root, returning the first ancestor holding a `debug-ui` folder.
  *
+ * @param startDir - Directory the ascent begins from.
+ * @param isFile - File probe used to confirm the assets exist.
+ * @returns The `debug-ui` asset directory, or `undefined` when no ancestor holds one.
+ */
+function ascendForAssets(startDir, isFile) {
+    let dir = startDir;
+    let parent = dirname(dir);
+    // how: probe each level then step up; the final probe covers the filesystem root, where parent === dir
+    while (parent !== dir) {
+        const found = probeAssetDir(dir, isFile);
+        if (found !== undefined) {
+            return found;
+        }
+        dir = parent;
+        parent = dirname(dir);
+    }
+    return probeAssetDir(dir, isFile);
+}
+/**
+ * Resolves the directory the compiled debug-UI assets ship in by ascending
+ * from the running module (located via `__dirname` in CommonJS or
+ * `import.meta.url` in ESM). The ascent finds the assets wherever the package
+ * lives — the built dist, an installed `node_modules` copy, or embedded
+ * inside a consumer's bundle output.
+ *
+ * @param isFile - File probe used to confirm the assets exist.
  * @returns The absolute debug-UI asset directory.
  */
-function defaultAssetRoot() {
-    /* istanbul ignore if -- @preserve the ESM build has no __dirname; the shipped CommonJS build and the test runner always define it */
-    if (typeof __dirname === 'undefined') {
-        throw createError('@hyperfrontend/features dev server self-location requires the CommonJS build; inject `assetRoot` otherwise.');
+function defaultAssetRoot(isFile) {
+    const located = ascendForAssets(currentModuleDir(), isFile);
+    if (located === undefined) {
+        throw createError('@hyperfrontend/features dev server could not locate the bundled debug-UI assets beside the running module; inject `assetRoot` to point at a directory containing the debug-UI `index.html`.');
     }
-    return join(__dirname, 'debug-ui');
+    return located;
 }
 /**
  * Reads the listening port from a server, throwing if the address is unexpectedly absent.
@@ -906,7 +1420,6 @@ function controlHandler(manifest, assetRoot, deps) {
  */
 async function startDevServer(config, deps = {}) {
     const createServer$1 = deps.createServer ?? createServer;
-    const assetRoot = deps.assetRoot ?? defaultAssetRoot();
     const servers = [];
     const apps = [];
     for (const app of config.apps) {
@@ -918,6 +1431,8 @@ async function startDevServer(config, deps = {}) {
     const manifest = { apps: apps.map((app) => ({ name: app.name, url: app.url })), debug: config.debug };
     let debugUrl;
     if (config.debug.enabled) {
+        // why: resolved only when the debug UI is enabled so consumers with it disabled never pay for (or fail on) asset self-location.
+        const assetRoot = deps.assetRoot ?? defaultAssetRoot(deps.isFile ?? isFile);
         const control = createServer$1(controlHandler(manifest, assetRoot, deps));
         const port = await listen(control, config.debugPort);
         servers.push(control);
@@ -931,10 +1446,23 @@ async function startDevServer(config, deps = {}) {
     };
 }
 
+/**
+ * Keeps the dev server running until a termination signal arrives, then closes
+ * every server so the command can exit cleanly.
+ *
+ * @param handle - The running dev server to close once a signal is received.
+ * @returns A promise that resolves after all servers have closed.
+ */
+async function holdUntilShutdown(handle) {
+    await waitForShutdown();
+    await handle.close();
+}
 /**
  * Resolves the `hf-dev.config.*` through the shared tiered loader and starts the
- * dev server: one static server per app plus the debug UI. The returned promise
- * resolves once the servers are listening; the process stays alive serving them.
+ * dev server: one static server per app plus the debug UI. After printing the
+ * server URLs the returned promise stays pending while the servers run; it
+ * resolves with the success code once a shutdown signal (`SIGINT`/`SIGTERM`,
+ * e.g. Ctrl-C) arrives and every server has closed cleanly.
  *
  * @param options - Flags, working directory, output sinks, and injectable deps.
  * @returns The process exit code.
@@ -949,6 +1477,7 @@ async function runDev(options) {
     const cwd = flags.cwd ? resolve(options.cwd, flags.cwd) : options.cwd;
     const resolveConfig = options.resolveConfig ?? resolveDevConfig;
     const startServer = options.startServer ?? startDevServer;
+    const waitForClose = options.waitForClose ?? holdUntilShutdown;
     try {
         const config = await resolveConfig({ cwd, flags });
         const handle = await startServer(config);
@@ -956,6 +1485,7 @@ async function runDev(options) {
         if (handle.debugUrl !== undefined) {
             stdout.write(`Debug UI: ${handle.debugUrl}\n`);
         }
+        await waitForClose(handle);
         return EXIT_OK;
     }
     catch (error) {
@@ -1131,7 +1661,7 @@ Usage: hf <command> [options]
 Commands:
   init     Scaffold the feature glue module and wire it into your app
   build    Generate the host connector, bundle it, and pack a tarball
-  dev      Resolve the dev-server config and start the debug UI
+  dev      Start the app servers and debug UI, serving until Ctrl-C
 
 Options:
   --name <name>         Feature name
@@ -1140,6 +1670,7 @@ Options:
   --entry <path>        Entry file to wire the glue import into (init)
   --url <url>           URL the connector loads the feature from (build)
   --protocol <none|v1|v2>  Security envelope enforced at build time
+  --allow-open          Acknowledge an explicit '--protocol none' and build an open, unauthenticated connector (build)
   --out <dir>           Output directory for the built connector (build)
   --apps <path>         Path to the dev-server apps array (dev)
   --port <number>       Port the dev-server debug UI listens on (dev)