@hyperfrontend/features 0.1.0 → 0.2.0

package/generators/index.d.ts

@@ -41,16 +41,16 @@ declare function generateFeatureModule(config: ResolvedFeatureConfig, contract:
  * 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)
  * ```
  */
 declare function generateMetadata(config: ResolvedFeatureConfig, contract: FeatureContract, tree: Tree): void;
@@ -58,9 +58,10 @@ declare function generateMetadata(config: ResolvedFeatureConfig, contract: Featu
 /**
  * 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.
@@ -68,7 +69,7 @@ declare function generateMetadata(config: ResolvedFeatureConfig, contract: Featu
  *
  * @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)
  * ```
  */
 declare function generateShell(config: ResolvedFeatureConfig, contract: FeatureContract, tree: Tree): void;

package/generators/index.esm.js

@@ -1,11 +1,12 @@
 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 { entries } from '../_dependencies/@hyperfrontend/immutable-api-utils/built-in-copy/object/index.esm.js';
+import { isAbsolute, join, relative, dirname } from 'node:path';
 import { 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 { 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 { generateFeatureModule } from '../_shared/generators/feature/generate-feature-module/index.esm.js';
 
 /**
@@ -81,43 +82,357 @@ export default contract
     tree.write(toDeclarationPath(config.contract), declaration);
 }
 
+// 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 && !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(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(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 (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 })
 }
 `;
 }
@@ -140,49 +455,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.
@@ -190,13 +564,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);
 }
 

package/generators/metadata/generate-metadata.d.ts

@@ -4,16 +4,16 @@ import type { FeatureContract, ResolvedFeatureConfig } from '../../shared/types'
  * 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)
  * ```
  */
 export declare function generateMetadata(config: ResolvedFeatureConfig, contract: FeatureContract, tree: Tree): void;

package/generators/metadata/generate-metadata.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"generate-metadata.d.ts","sourceRoot":"","sources":["../../../../../../../../libs/features/src/generators/metadata/generate-metadata.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,kCAAkC,CAAA;AAC5D,OAAO,KAAK,EAAE,eAAe,EAAE,qBAAqB,EAAE,MAAM,oBAAoB,CAAA;AAQhF;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,qBAAqB,EAAE,QAAQ,EAAE,eAAe,EAAE,IAAI,EAAE,IAAI,GAAG,IAAI,CAS3G"}
+{"version":3,"file":"generate-metadata.d.ts","sourceRoot":"","sources":["../../../../../../../../libs/features/src/generators/metadata/generate-metadata.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,kCAAkC,CAAA;AAC5D,OAAO,KAAK,EAAE,eAAe,EAAE,qBAAqB,EAAE,MAAM,oBAAoB,CAAA;AAQhF;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,qBAAqB,EAAE,QAAQ,EAAE,eAAe,EAAE,IAAI,EAAE,IAAI,GAAG,IAAI,CAU3G"}

package/generators/shell/connector-types.d.ts

@@ -0,0 +1,19 @@
+import type { FeatureContract } from '../../shared/types';
+/**
+ * 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 }"
+ * ```
+ */
+export declare function buildConnectorTypes(contract: FeatureContract): string;
+//# sourceMappingURL=connector-types.d.ts.map

package/generators/shell/connector-types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"connector-types.d.ts","sourceRoot":"","sources":["../../../../../../../../libs/features/src/generators/shell/connector-types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAqB,eAAe,EAAE,MAAM,oBAAoB,CAAA;AAgK5E;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,eAAe,GAAG,MAAM,CAYrE"}

package/generators/shell/generate-shell.d.ts

@@ -3,9 +3,10 @@ import type { FeatureContract, ResolvedFeatureConfig } from '../../shared/types'
 /**
  * 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.
@@ -13,7 +14,7 @@ import type { FeatureContract, ResolvedFeatureConfig } from '../../shared/types'
  *
  * @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)
  * ```
  */
 export declare function generateShell(config: ResolvedFeatureConfig, contract: FeatureContract, tree: Tree): void;

package/generators/shell/generate-shell.d.ts.map

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