@hyperfrontend/features 0.1.0 → 0.2.0

package/cli/usage.d.ts

@@ -4,5 +4,5 @@
  * Documents the three commands and the shared flag surface so the headless
  * (`--ci`) path is discoverable without reading the docs.
  */
-export declare const USAGE = "@hyperfrontend/features \u2014 build, embed, and orchestrate micro-frontend features\n\nUsage: hf <command> [options]\n\nCommands:\n  init     Scaffold the feature glue module and wire it into your app\n  build    Generate the host connector, bundle it, and pack a tarball\n  dev      Resolve the dev-server config and start the debug UI\n\nOptions:\n  --name <name>         Feature name\n  --version <version>   Feature version\n  --contract <path>     Path to the *.contract.{json,ts,js} file\n  --entry <path>        Entry file to wire the glue import into (init)\n  --url <url>           URL the connector loads the feature from (build)\n  --protocol <none|v1|v2>  Security envelope enforced at build time\n  --out <dir>           Output directory for the built connector (build)\n  --apps <path>         Path to the dev-server apps array (dev)\n  --port <number>       Port the dev-server debug UI listens on (dev)\n  --config <path>       Path to the whole feature.config.* / hf-dev.config.* file\n  --cwd <dir>           Working-directory override\n  --ci, --yes           Run headlessly; error on any unresolved required key\n  --dry-run             Preview file changes without writing them\n  -h, --help            Print this help\n";
+export declare const USAGE = "@hyperfrontend/features \u2014 build, embed, and orchestrate micro-frontend features\n\nUsage: hf <command> [options]\n\nCommands:\n  init     Scaffold the feature glue module and wire it into your app\n  build    Generate the host connector, bundle it, and pack a tarball\n  dev      Start the app servers and debug UI, serving until Ctrl-C\n\nOptions:\n  --name <name>         Feature name\n  --version <version>   Feature version\n  --contract <path>     Path to the *.contract.{json,ts,js} file\n  --entry <path>        Entry file to wire the glue import into (init)\n  --url <url>           URL the connector loads the feature from (build)\n  --protocol <none|v1|v2>  Security envelope enforced at build time\n  --allow-open          Acknowledge an explicit '--protocol none' and build an open, unauthenticated connector (build)\n  --out <dir>           Output directory for the built connector (build)\n  --apps <path>         Path to the dev-server apps array (dev)\n  --port <number>       Port the dev-server debug UI listens on (dev)\n  --config <path>       Path to the whole feature.config.* / hf-dev.config.* file\n  --cwd <dir>           Working-directory override\n  --ci, --yes           Run headlessly; error on any unresolved required key\n  --dry-run             Preview file changes without writing them\n  -h, --help            Print this help\n";
 //# sourceMappingURL=usage.d.ts.map

package/cli/usage.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"usage.d.ts","sourceRoot":"","sources":["../../../../../../../libs/features/src/cli/usage.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,eAAO,MAAM,KAAK,+tCAwBjB,CAAA"}
+{"version":3,"file":"usage.d.ts","sourceRoot":"","sources":["../../../../../../../libs/features/src/cli/usage.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,eAAO,MAAM,KAAK,21CAyBjB,CAAA"}

package/generators/feature/generate-feature-module.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"generate-feature-module.d.ts","sourceRoot":"","sources":["../../../../../../../../libs/features/src/generators/feature/generate-feature-module.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,kCAAkC,CAAA;AAC5D,OAAO,KAAK,EAAE,eAAe,EAAE,qBAAqB,EAAE,MAAM,oBAAoB,CAAA;AAmDhF;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,qBAAqB,EAAE,QAAQ,EAAE,eAAe,EAAE,IAAI,EAAE,IAAI,GAAG,IAAI,CAEhH"}
+{"version":3,"file":"generate-feature-module.d.ts","sourceRoot":"","sources":["../../../../../../../../libs/features/src/generators/feature/generate-feature-module.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,kCAAkC,CAAA;AAC5D,OAAO,KAAK,EAAE,eAAe,EAAE,qBAAqB,EAAE,MAAM,oBAAoB,CAAA;AA2DhF;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,qBAAqB,EAAE,QAAQ,EAAE,eAAe,EAAE,IAAI,EAAE,IAAI,GAAG,IAAI,CAEhH"}

package/generators/index.cjs.js

@@ -3,6 +3,7 @@
 const index_cjs_js = require('../_dependencies/@hyperfrontend/immutable-api-utils/built-in-copy/array/index.cjs.js');
 const index_cjs_js$2 = require('../_dependencies/@hyperfrontend/immutable-api-utils/built-in-copy/json/index.cjs.js');
 const index_cjs_js$1 = require('../_dependencies/@hyperfrontend/immutable-api-utils/built-in-copy/object/index.cjs.js');
+const node_path = require('node:path');
 const index_cjs_js$3 = require('../_dependencies/@hyperfrontend/project-scope/vfs/index.cjs.js');
 const index_cjs_js$4 = require('../_dependencies/@hyperfrontend/versioning/semver/format/index.cjs.js');
 const index_cjs_js$5 = require('../_dependencies/@hyperfrontend/versioning/semver/parse/index.cjs.js');
@@ -83,25 +84,32 @@ export default contract
 // 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 `/**
@@ -114,7 +122,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 })
@@ -143,7 +151,7 @@ ${emits}
  * ```
  */
 function generateFeatureModule(config, contract, tree) {
-    tree.write(MODULE_PATH, buildFeatureModule(config, contract), { mode: index_cjs_js$3.Mode.SkipIfExists });
+    tree.write(MODULE_PATH, buildFeatureModule(config, contract, tree.root), { mode: index_cjs_js$3.Mode.SkipIfExists });
 }
 
 // note: Human- and registry-facing sidecar; the bundled connector inlines its own copy of the contract.
@@ -152,16 +160,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) {
@@ -170,6 +178,7 @@ function generateMetadata(config, contract, tree) {
         version: index_cjs_js$4.format(index_cjs_js$5.parseVersionStrict(config.version)),
         url: config.url,
         contract,
+        ...(config.protocol !== undefined && { protocol: config.protocol }),
         generatedBy: '@hyperfrontend/features',
     };
     tree.write(METADATA_PATH, `${index_cjs_js$2.stringify(metadata, null, 2)}\n`);
@@ -218,6 +227,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.
@@ -244,6 +258,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);
@@ -291,43 +311,357 @@ function toSourceLiteral(value, indent = '') {
     return index_cjs_js$2.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(value) {
+    return typeof value === 'object' && value !== null && !index_cjs_js.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$2.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(schema['properties']) ? index_cjs_js$1.entries(schema['properties']) : [];
+    if (properties.length === 0) {
+        return 'Record<string, unknown>';
+    }
+    const required = index_cjs_js.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(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(schema)) {
+        return 'unknown';
+    }
+    const enumMembers = schema['enum'];
+    if (index_cjs_js.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 })
 }
 `;
 }
@@ -350,49 +684,108 @@ function buildConnectorPackageJson(config) {
     };
     return `${index_cjs_js$2.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.
@@ -400,13 +793,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);
 }