@hyperfrontend/features 0.1.0 → 0.2.0

package/bin/hf.js

@@ -3,15 +3,14 @@
 
 const index_cjs_js = require('../_dependencies/@hyperfrontend/immutable-api-utils/built-in-copy/error/index.cjs.js');
 const node_child_process = require('node:child_process');
-const node_os = require('node:os');
 const node_path = require('node:path');
 const index_cjs_js$8 = require('../_dependencies/@hyperfrontend/builder/index.cjs.js');
+const index_cjs_js$4 = require('../_dependencies/@hyperfrontend/immutable-api-utils/built-in-copy/array/index.cjs.js');
 const index_cjs_js$3 = require('../_dependencies/@hyperfrontend/immutable-api-utils/built-in-copy/json/index.cjs.js');
 const index_cjs_js$6 = require('../_dependencies/@hyperfrontend/project-scope/core/fs/index.cjs.js');
 const index_cjs_js$7 = require('../_dependencies/@hyperfrontend/project-scope/vfs/index.cjs.js');
 const index_cjs_js$1 = require('../_dependencies/@hyperfrontend/versioning/semver/format/index.cjs.js');
 const index_cjs_js$2 = require('../_dependencies/@hyperfrontend/versioning/semver/parse/index.cjs.js');
-const index_cjs_js$4 = require('../_dependencies/@hyperfrontend/immutable-api-utils/built-in-copy/array/index.cjs.js');
 const index_cjs_js$5 = require('../_dependencies/@hyperfrontend/immutable-api-utils/built-in-copy/object/index.cjs.js');
 require('../_dependencies/@hyperfrontend/json-utils/index.cjs.js');
 const node_url = require('node:url');
@@ -21,6 +20,7 @@ const index_cjs_js$a = require('../_dependencies/@hyperfrontend/immutable-api-ut
 const index_cjs_js$c = require('../_dependencies/@hyperfrontend/project-scope/heuristics/entry-points/index.cjs.js');
 const index_cjs_js$b = require('../_dependencies/@hyperfrontend/questions/index.cjs.js');
 
+var _documentCurrentScript = typeof document !== 'undefined' ? document.currentScript : null;
 /** Value-taking flags mapped to their {@link CliFlags} key. */
 const STRING_FLAGS = {
     '--name': 'name',
@@ -37,6 +37,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',
@@ -86,6 +87,7 @@ function parseCliArgs(argv) {
     }
     const flags = {
         ...strings,
+        allowOpen: booleans['allowOpen'] ?? false,
         ci: booleans['ci'] ?? false,
         yes: booleans['yes'] ?? false,
         dryRun: booleans['dryRun'] ?? false,
@@ -100,16 +102,16 @@ const METADATA_PATH = 'metadata.json';
  * Stages the connector's `metadata.json` describing the feature and its contract.
  *
  * Stamps a canonical version string via `@hyperfrontend/versioning` and embeds
- * the contract so humans and the registry can inspect the feature without
- * unpacking the bundle.
+ * the contract and the baked security protocol so humans and the registry can
+ * inspect the feature without unpacking the bundle.
  *
- * @param config - The resolved feature config supplying name, version, and URL.
+ * @param config - The resolved feature config supplying name, version, URL, and protocol.
  * @param contract - The validated contract embedded for inspection.
  * @param tree - The VFS tree the metadata file is staged into.
  *
  * @example Staging metadata for the clock feature
  * ```typescript
- * generateMetadata({ name: 'clock', version: '1.0.0', contract: './clock.contract.json', url: '/clock' }, contract, tree)
+ * generateMetadata({ name: 'clock', version: '1.0.0', contract: './clock.contract.json', url: '/clock', protocol: 'v2' }, contract, tree)
  * ```
  */
 function generateMetadata(config, contract, tree) {
@@ -118,6 +120,7 @@ function generateMetadata(config, contract, tree) {
         version: index_cjs_js$1.format(index_cjs_js$2.parseVersionStrict(config.version)),
         url: config.url,
         contract,
+        ...(config.protocol !== undefined && { protocol: config.protocol }),
         generatedBy: '@hyperfrontend/features',
     };
     tree.write(METADATA_PATH, `${index_cjs_js$3.stringify(metadata, null, 2)}\n`);
@@ -166,6 +169,11 @@ function isIdentifier(key) {
  *
  * @param value - The string to render.
  * @returns A single-quoted, safely escaped string literal.
+ *
+ * @example Quoting a string containing a single quote
+ * ```typescript
+ * quoteString("it's") // => "'it\\'s'"
+ * ```
  */
 function quoteString(value) {
     // how: JSON encoding already escapes backslashes and control chars; we scan it to swap quote conventions (unescape \" to ", escape ' to \') while copying every other escape verbatim, so an input backslash stays intact.
@@ -192,6 +200,12 @@ function quoteString(value) {
  *
  * @param key - The property name.
  * @returns The key as written in an object literal.
+ *
+ * @example Formatting identifier and non-identifier keys
+ * ```typescript
+ * formatKey('url') // => 'url'
+ * formatKey('time-zone') // => "'time-zone'"
+ * ```
  */
 function formatKey(key) {
     return isIdentifier(key) ? key : quoteString(key);
@@ -239,43 +253,357 @@ function toSourceLiteral(value, indent = '') {
     return index_cjs_js$3.stringify(value);
 }
 
+// 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 && !index_cjs_js$4.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 index_cjs_js$3.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']) ? index_cjs_js$5.entries(schema['properties']) : [];
+    if (properties.length === 0) {
+        return 'Record<string, unknown>';
+    }
+    const required = index_cjs_js$4.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 (index_cjs_js$4.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 })
 }
 `;
 }
@@ -298,49 +626,108 @@ function buildConnectorPackageJson(config) {
     };
     return `${index_cjs_js$3.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.
@@ -348,13 +735,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);
 }
 
@@ -391,6 +778,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.`);
+        }
     });
 }
 /**
@@ -416,7 +828,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
@@ -431,6 +843,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 index_cjs_js.createError(`Invalid contract:\n${issues.map((issue) => `  - ${issue}`).join('\n')}`);
     }
@@ -571,7 +989,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
@@ -592,7 +1010,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 index_cjs_js.createError(`Invalid protocol: "${String(protocol)}" (expected none, v1, or v2).`);
     }
@@ -603,8 +1023,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 }) };
 }
 
 /** Exit code for a successful command run. */
@@ -654,9 +1081,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.
@@ -674,23 +1104,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 ?? node_path.join(DEFAULT_OUT, `${config.name}-shell`));
         if (flags.dryRun) {
             stdout.write(`Would build "${config.name}" → ${out} [dry run]\n`);
             return EXIT_OK;
         }
-        tempDir = node_path.join(node_os.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 = node_path.join(cwd, `.hf-shell-${config.name.replace(/[^a-z0-9-]/gi, '-')}-${process.pid}`);
         index_cjs_js$6.createDirectory(tempDir, { recursive: true });
         const tree = index_cjs_js$7.createTree(tempDir);
         generateShell(config, contract, tree);
         tree.write('tsconfig.lib.json', buildTsConfig());
         index_cjs_js$7.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;
@@ -704,6 +1145,23 @@ async function runBuild(options) {
             index_cjs_js$6.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) {
+    index_cjs_js$6.writeFileContent(node_path.join(out, 'README.md'), index_cjs_js$6.readFileContent(node_path.join(tempDir, 'README.md')));
+    index_cjs_js$6.writeFileContent(node_path.join(out, 'metadata.json'), index_cjs_js$6.readFileContent(node_path.join(tempDir, 'metadata.json')));
+    const manifestPath = node_path.join(out, 'package.json');
+    const manifest = index_cjs_js$6.readJsonFileIfExists(manifestPath);
+    if (manifest !== null && index_cjs_js$4.isArray(manifest['files'])) {
+        index_cjs_js$6.writeJsonFile(manifestPath, { ...manifest, files: [...manifest['files'], 'metadata.json'] });
+    }
+}
 /**
  * Builds the minimal `tsconfig.lib.json` the builder reads for declarations.
  *
@@ -715,6 +1173,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,
@@ -898,6 +1358,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 node_path.dirname(node_url.fileURLToPath((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('hf.js', document.baseURI).href))));
+}
+
 // 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 = index_cjs_js$5.freeze({
     '.html': 'text/html; charset=utf-8',
@@ -1006,23 +1489,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 = node_path.join(dir, 'debug-ui');
+    if (isFile(node_path.join(sibling, 'index.html'))) {
+        return sibling;
+    }
+    const nested = node_path.join(dir, 'server', 'debug-ui');
+    return isFile(node_path.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 = node_path.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 = node_path.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 index_cjs_js.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 index_cjs_js.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 node_path.join(__dirname, 'debug-ui');
+    return located;
 }
 /**
  * Reads the listening port from a server, throwing if the address is unexpectedly absent.
@@ -1133,7 +1659,6 @@ function controlHandler(manifest, assetRoot, deps) {
  */
 async function startDevServer(config, deps = {}) {
     const createServer = deps.createServer ?? node_http.createServer;
-    const assetRoot = deps.assetRoot ?? defaultAssetRoot();
     const servers = [];
     const apps = [];
     for (const app of config.apps) {
@@ -1145,6 +1670,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 ?? index_cjs_js$6.isFile);
         const control = createServer(controlHandler(manifest, assetRoot, deps));
         const port = await listen(control, config.debugPort);
         servers.push(control);
@@ -1158,10 +1685,46 @@ async function startDevServer(config, deps = {}) {
     };
 }
 
+/**
+ * Resolve once the process receives an interrupt or terminate signal.
+ *
+ * Used by the dev command and long-running executors to stay alive after
+ * startup and tear down gracefully when the user (or the task runner) stops
+ * them.
+ *
+ * @returns A promise that settles when `SIGINT` or `SIGTERM` is received.
+ *
+ * @example Stay alive until the target is stopped
+ * ```ts
+ * await waitForShutdown()
+ * await handle.close()
+ * ```
+ */
+function waitForShutdown() {
+    return index_cjs_js$a.createPromise((resolve) => {
+        for (const signal of ['SIGINT', 'SIGTERM']) {
+            process.once(signal, () => resolve());
+        }
+    });
+}
+
+/**
+ * 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.
@@ -1176,6 +1739,7 @@ async function runDev(options) {
     const cwd = flags.cwd ? node_path.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);
@@ -1183,6 +1747,7 @@ async function runDev(options) {
         if (handle.debugUrl !== undefined) {
             stdout.write(`Debug UI: ${handle.debugUrl}\n`);
         }
+        await waitForClose(handle);
         return EXIT_OK;
     }
     catch (error) {
@@ -1194,25 +1759,32 @@ async function runDev(options) {
 // note: Write-once target; re-runs never clobber handlers the author has filled in.
 const MODULE_PATH = 'src/hyperfrontend.feature.ts';
 /**
- * Derives the extensionless, relative import specifier for the contract module.
+ * Derives the extensionless import specifier for the contract module, computed
+ * relative to the directory the integration module is written into.
  *
- * @param contractPath - The config's contract path (e.g. `contracts/clock.contract.json`).
- * @returns A relative specifier suitable for an `import` statement.
+ * @param contractPath - The config's contract path, tree-root-relative or absolute.
+ * @param treeRoot - Absolute root of the tree the integration module is staged into.
+ * @returns A POSIX-style relative specifier suitable for an `import` statement.
  */
-function toContractImportPath(contractPath) {
+function toContractImportPath(contractPath, treeRoot) {
     const withoutExtension = contractPath.replace(/\.(json|ts|js)$/, '');
-    return /^[./]/.test(withoutExtension) ? withoutExtension : `./${withoutExtension}`;
+    const target = node_path.isAbsolute(withoutExtension) ? withoutExtension : node_path.join(treeRoot, withoutExtension);
+    const specifier = node_path.relative(node_path.join(treeRoot, node_path.dirname(MODULE_PATH)), target)
+        .split('\\')
+        .join('/');
+    return specifier.startsWith('.') ? specifier : `./${specifier}`;
 }
 /**
  * Builds the feature integration module source from the contract.
  *
  * @param config - The resolved feature config naming the feature and contract path.
  * @param contract - The validated contract whose actions drive the scaffolded stubs.
+ * @param treeRoot - Absolute root the config's contract path is relative to.
  * @returns The integration module source as a string.
  */
-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 `/**
@@ -1225,7 +1797,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 })
@@ -1254,7 +1826,7 @@ ${emits}
  * ```
  */
 function generateFeatureModule(config, contract, tree) {
-    tree.write(MODULE_PATH, buildFeatureModule(config, contract), { mode: index_cjs_js$7.Mode.SkipIfExists });
+    tree.write(MODULE_PATH, buildFeatureModule(config, contract, tree.root), { mode: index_cjs_js$7.Mode.SkipIfExists });
 }
 
 // note: Token searched for to keep insertion idempotent; deleting the block reverses the mutation.
@@ -1538,7 +2110,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
@@ -1547,6 +2119,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)