@process.co/element-types 0.0.18 → 0.0.20

package/src/define-signal-app-prop.test-d.ts

@@ -0,0 +1,44 @@
+/**
+ * Compile-only: embedded `defineApp` in signal `props` (not emitted).
+ */
+import {
+    defineApp,
+    defineSignal,
+    type DeriveEmbeddedAppPropInstance,
+    type DeriveSignalInstance,
+} from './index';
+
+const httpApp = defineApp({
+    type: 'app',
+    app: 'http',
+    noAuth: true,
+    propDefinitions: {
+        httpRequest: {
+            type: 'http_request',
+            label: 'HTTP Request Configuration',
+        },
+    },
+} as const);
+
+const _signal = defineSignal({
+    type: 'signal',
+    props: {
+        httpInterface: { type: '$.interface.http' },
+        http: httpApp,
+    },
+    async run() {
+        this.http.httpRequest.execute;
+        this.httpInterface.deferHttpResponse;
+    },
+});
+
+export type _HttpOnThis = DeriveSignalInstance<typeof _signal>['http'];
+export type _HttpRuntime = DeriveEmbeddedAppPropInstance<typeof httpApp>;
+type _assertHttpProp = _HttpOnThis extends _HttpRuntime ? true : false;
+const _httpPropCheck: _assertHttpProp = true;
+type _assertNotDefinition = 'type' extends keyof _HttpOnThis ? false : true;
+const _notDefinitionCheck: _assertNotDefinition = true;
+type _assertHttpRequest = _HttpOnThis['httpRequest'] extends { execute: () => Promise<unknown> }
+    ? true
+    : false;
+const _httpRequestCheck: _assertHttpRequest = true;

package/src/define-signal-hook-this.test-d.ts

@@ -0,0 +1,49 @@
+/**
+ * Compile-only checks for defineSignal hook vs run `this` (not emitted).
+ */
+import {
+    defineSignal,
+    type SignalRunHostServices,
+    type SignalSaveHostParameters,
+} from './index';
+
+const _webhook = defineSignal({
+    type: 'signal',
+    props: {
+        httpInterface: { type: '$.interface.http' },
+        cacheMaxAge: { type: '$.interface.duration', default: 86400 },
+        authType: { type: 'string', default: 'none' },
+    },
+    hooks: {
+        async save({ $ }) {
+            const _draft: boolean = $.isDraft;
+            void _draft;
+            await $.http.configureResponseCaching({
+                maxAge: this.cacheMaxAge,
+                varyBy: '*',
+            });
+            // @ts-expect-error — `run` host `$` is not available in hooks.save
+            $.enforceSchema;
+            // @ts-expect-error — `$emit` is only on `run` `this`, not hooks
+            this.$emit;
+            // @ts-expect-error — no runtime HTTP interface on hook `this`
+            await this.httpInterface.respond({ status: 200, body: {} });
+        },
+    },
+    async run({ $, event }) {
+        void event;
+        $.enforceSchema;
+        // @ts-expect-error — save-only host `$` is not available in run
+        $.http;
+        await this.httpInterface.deferHttpResponse(30_000);
+    },
+});
+
+export type _webhookType = typeof _webhook;
+
+type _saveParams = Parameters<NonNullable<typeof _webhook.hooks>['save']>[0];
+type _saveDollar = _saveParams['$'];
+type _assertSaveDollar = _saveDollar extends SignalSaveHostParameters['$'] ? true : false;
+const _saveDollarCheck: _assertSaveDollar = true;
+type _saveDollarNotRun = SignalRunHostServices extends _saveDollar ? false : true;
+const _saveDollarNotRunCheck: _saveDollarNotRun = true;

package/src/http-request-cache.ts

@@ -0,0 +1,56 @@
+/**
+ * HTTP response replay cache — policy at save, vary key at runtime.
+ */
+
+export type HttpRequestCacheMode = 'cache-only' | 'stale-while-revalidate';
+
+/** Materialized at save → elementData.$httpRequestCachePolicy */
+export type HttpRequestCachePolicy = {
+    mode: HttpRequestCacheMode;
+    ttlSeconds: number;
+    refreshAfterSeconds?: number;
+    vary: HttpRequestCacheVary;
+    /** When true, webhook loads trigger so author can call setRequestVaryKey. */
+    needsRuntimeVaryKey?: boolean;
+};
+
+export type HttpRequestCacheVary = {
+    headers?: Array<{ name: string; lowerCase?: boolean }>;
+    clientIp?: boolean;
+    pathTemplate?: string;
+    query?: string[];
+    body?: BodyVaryProjection;
+};
+
+/** Boolean leaves select fields; nested objects recurse. */
+export type BodyVaryProjection = {
+    [key: string]: boolean | BodyVaryProjection;
+};
+
+/** Editor wire for $.interface.cacheVaryInfo */
+export type CacheVaryInfoWire = {
+    headers?: Array<{ name: string }>;
+    query?: string[];
+    clientIp?: boolean;
+    pathTemplate?: string;
+    bodyPaths?: BodyVaryProjection;
+    customRuntimeKey?: boolean;
+};
+
+/** Seconds (TTL). $.interface.duration */
+export type DurationWire = number;
+
+/** Save-only: hooks.save → $.http.configureResponseCaching */
+export type ConfigureResponseCachingOptions = {
+    maxAge: number;
+    varyBy: HttpRequestCacheVary | CacheVaryInfoWire | '*' | string[];
+    mode?: HttpRequestCacheMode;
+    refreshAfterSeconds?: number;
+    needsRuntimeVaryKey?: boolean;
+};
+
+export const HTTP_REQUEST_CACHE_POLICY_KEY = '$httpRequestCachePolicy' as const;
+
+export const REPLAY_BINDING_RANGE = '$replayBinding' as const;
+
+export const REPLAY_META_RANGE = '$replayMeta' as const;

package/src/index.ts

@@ -21,6 +21,7 @@ import type {
     ISlotStaticInstanceDefinition,
     ISlotDefinition,
 } from './slot-definition';
+import { ConfigureResponseCachingOptions } from './http-request-cache';
 
 export type { ISlotInstanceDefinition, ISlotStaticInstanceDefinition, ISlotDefinition };
 
@@ -60,6 +61,19 @@ export {
     isPlatformBoundLoaderType,
 } from './platform-loader-type';
 
+export {
+    HTTP_REQUEST_CACHE_POLICY_KEY,
+    REPLAY_BINDING_RANGE,
+    REPLAY_META_RANGE,
+    type BodyVaryProjection,
+    type CacheVaryInfoWire,
+    type ConfigureResponseCachingOptions,
+    type DurationWire,
+    type HttpRequestCacheMode,
+    type HttpRequestCachePolicy,
+    type HttpRequestCacheVary,
+} from './http-request-cache';
+
 // Base types for module definitions
 export type ModuleDefinition = {
     type: string;
@@ -110,7 +124,7 @@ export type SignalEventShape = {
  * When {@link HttpInterfaceSchemaWire.validation} is true, the runtime does **not** validate against
  * those JSON blobs alone: it loads the ESM at {@link HttpInterfaceSchemaWire.compiledValidatorKey}
  * (default export = Zod schema) and runs full `safeParse` on the payload via the runner-bound
- * {@link SignalHostServices.enforceSchema} RPC (see {@link setSignalEmitValidationHost}).
+ * {@link SignalRunHostServices.enforceSchema} RPC (see {@link setSignalEmitValidationHost}).
  */
 export type HttpInterfaceSchemaWire = {
     /**
@@ -141,9 +155,13 @@ export type HttpInterfaceSchemaWire = {
     coerceLeafPrimitives?: boolean | 'auto';
 };
 
-/** Host-backed RPC surface passed as `params.$` to signal `run` (parallel to action `ActionRunOptions.$`). */
-export type SignalHostServices = {
+/**
+ * Host `params.$` during signal **`run`** (live webhook / test execution).
+ * Not passed to `hooks.save` — use {@link SignalSaveHookHostServices} there.
+ */
+export type SignalRunHostServices = {
     export: (category: string, message: string) => void | Promise<void>;
+
     $transitionToSlot: (slots: Array<SlotTransitionDefinition>) => void | Promise<void>;
 
     /**
@@ -158,12 +176,54 @@ export type SignalHostServices = {
 
     /**
      * Wire for the primary `$.interface.schema` property (same persisted object the publish
-     * pipeline attaches `compiledValidatorKey` to). Use with {@link SignalHostServices.enforceSchema},
+     * pipeline attaches `compiledValidatorKey` to). Use with {@link SignalRunHostServices.enforceSchema},
      * e.g. `await $.enforceSchema($.interfaceEmitSchema, toEmit)`.
      */
     interfaceEmitSchema?: HttpInterfaceSchemaWire;
 };
 
+/** @deprecated Use {@link SignalRunHostServices} for `run`; hook `$` types are separate. */
+export type SignalHostServices = SignalRunHostServices;
+
+/** Shared on all signal hook `params.$` surfaces. */
+export type SignalHookHostContext = {
+    /**
+     * `true` when the hook runs during draft/editor materialization;
+     * `false` on publish / production hook runs.
+     */
+    isDraft: boolean;
+};
+
+/** Host `params.$` during **`hooks.save`**. */
+export type SignalSaveHookHostServices = SignalHookHostContext & {
+    http: {
+        configureResponseCaching: (
+            options: ConfigureResponseCachingOptions,
+        ) => Promise<void> | void;
+    };
+};
+
+/** @deprecated Use {@link SignalSaveHookHostServices} */
+export type HookSaveHostServices = SignalSaveHookHostServices;
+
+/** Host `params.$` during `hooks.activate` / `hooks.deactivate`. */
+export type SignalLifecycleHookHostServices = SignalHookHostContext &
+    Pick<SignalRunHostServices, 'export'>;
+
+/** Inputs used to resolve {@link SignalHookHostContext.isDraft} in the API runner. */
+export type SignalHookDraftContextInput = {
+    isDraft?: boolean;
+    executionContext?: 'editor' | 'production' | 'test' | 'webhook' | (string & {});
+};
+
+/** Resolve `$.isDraft` for hook invocations (explicit flag wins; else `executionContext === 'editor'`). */
+export function resolveSignalHookIsDraft(ctx: SignalHookDraftContextInput): boolean {
+    if (typeof ctx.isDraft === 'boolean') {
+        return ctx.isDraft;
+    }
+    return ctx.executionContext === 'editor';
+}
+
 /** One row from a failed Zod `safeParse` (host / `validateEmitPayload`). */
 export type SchemaValidationIssue = {
     path: string;
@@ -193,7 +253,7 @@ export type EnforceSchemaResult<T extends unknown = unknown> =
 export const PROCESS_CO_ENFORCE_SCHEMA_HOST_PAYLOAD_MARKER = 'enforceSchema' as const;
 
 export type SignalRunOptions = {
-    $: SignalHostServices;
+    $: SignalRunHostServices;
     event: SignalEventShape;
 };
 
@@ -206,10 +266,10 @@ const SIGNAL_EMIT_VALIDATION_HOST = Symbol.for('process.co.signalEmitValidationH
 
 /**
  * Host shape accepted from the runner RPC bridge (`$.enforceSchema` may be typed as
- * returning `Promise<unknown>` while {@link SignalHostServices} uses a generic `T`).
+ * returning `Promise<unknown>` while {@link SignalRunHostServices} uses a generic `T`).
  */
 export type SignalEmitValidationHostBinding =
-    | Pick<SignalHostServices, 'enforceSchema'>
+    | Pick<SignalRunHostServices, 'enforceSchema'>
     | {
         enforceSchema?: (
             inputSchema: HttpInterfaceSchemaWire | undefined,
@@ -217,8 +277,8 @@ export type SignalEmitValidationHostBinding =
         ) => Promise<unknown>;
     };
 
-function getSignalEmitValidationHostBinding(): Pick<SignalHostServices, 'enforceSchema'> | undefined {
-    return (globalThis as Record<symbol, Pick<SignalHostServices, 'enforceSchema'> | undefined>)[
+function getSignalEmitValidationHostBinding(): Pick<SignalRunHostServices, 'enforceSchema'> | undefined {
+    return (globalThis as Record<symbol, Pick<SignalRunHostServices, 'enforceSchema'> | undefined>)[
         SIGNAL_EMIT_VALIDATION_HOST
     ];
 }
@@ -232,11 +292,11 @@ function getSignalEmitValidationHostBinding(): Pick<SignalHostServices, 'enforce
 export function setSignalEmitValidationHost(
     host: SignalEmitValidationHostBinding | undefined,
 ): void {
-    const g = globalThis as Record<symbol, Pick<SignalHostServices, 'enforceSchema'> | undefined>;
+    const g = globalThis as Record<symbol, Pick<SignalRunHostServices, 'enforceSchema'> | undefined>;
     if (host === undefined) {
         delete g[SIGNAL_EMIT_VALIDATION_HOST];
     } else {
-        g[SIGNAL_EMIT_VALIDATION_HOST] = host as Pick<SignalHostServices, 'enforceSchema'>;
+        g[SIGNAL_EMIT_VALIDATION_HOST] = host as Pick<SignalRunHostServices, 'enforceSchema'>;
     }
 }
 
@@ -663,10 +723,12 @@ type PropDefinitionInput<TType = unknown> = BasePropDefinition & {
 };
 
 export type HttpInterfaceType = {
+
     /**
      * Full HTTP response (status / headers / body). Sending `body` completes the exchange for typical requests.
      */
     respond: (response: HTTPResponse) => Promise<any> | void;
+
     /**
      * Incremental write or SSE frame; does not complete the exchange. Pair with {@link end} or a terminal {@link respond} where applicable.
      */
@@ -680,6 +742,12 @@ export type HttpInterfaceType = {
      */
     deferHttpResponse: (timeoutMs?: number, options?: HttpDeferResponseOptions) => void;
 
+    /**
+     * Optional runtime vary suffix (hashed and appended to the HTTP base scenario key).
+     * Call when saved `$httpRequestCachePolicy.needsRuntimeVaryKey` is true.
+     */
+    setRequestVaryKey: (value: string) => void;
+
     /**
      * Append one JSON value to an incremental stream (`ndjson` or `jsonArray` defer modes). Each call is one line (NDJSON) or one array element (json-array).
      */
@@ -693,6 +761,7 @@ export type HttpInterfaceType = {
     flow: FlowFunctions;
     end: () => void;
     execute: () => Promise<{ headers?: Record<string, string>;[key: string]: any }>
+
 };
 
 
@@ -729,12 +798,32 @@ type PropTypeFromTypeValue<U, T = unknown> =
     : U extends "integer" ? number
     : U extends "$.interface.schema" ? HttpInterfaceSchemaWire
     : U extends "$.interface.http" ? HttpInterfaceType
+    : U extends "$.interface.duration" ? import('./http-request-cache').DurationWire
+    : U extends "$.interface.cacheVaryInfo" ? import('./http-request-cache').CacheVaryInfoWire
     : unknown;
 
+/**
+ * Runtime shape of an embedded app prop (`props: { http: httpApp }` on a signal/action).
+ * Maps `propDefinitions` / `props` / `methods` to instance fields — not the `defineApp` module metadata (`type`, `app`, …).
+ */
+export type DeriveEmbeddedAppPropInstance<T extends { type: 'app' }> = Spread<
+    (T extends { propDefinitions: Record<string, any> }
+        ? { [K in keyof T['propDefinitions']]: PropType<T['propDefinitions'][K]> }
+        : {}) &
+        (T extends { props: Record<string, any> }
+            ? { [K in keyof T['props']]: PropType<T['props'][K]> }
+            : {}) &
+        (T extends { methods: Record<string, any> }
+            ? { [K in keyof T['methods']]: T['methods'][K] }
+            : {})
+>;
+
 // Utility type for transforming prop definitions to their runtime types
 export type PropType<T> =
-    // 1. If T is an app definition, derive its instance type
-    T extends { props: Record<string, any>; methods: Record<string, any> }
+    // 1. Embedded app module → runtime prop surface (not the definition object)
+    T extends { type: 'app' }
+    ? DeriveEmbeddedAppPropInstance<T>
+    : T extends { props: Record<string, any>; methods: Record<string, any> }
     ? DeriveAppInstance<T>
     // 2. If T is a propDefinition, resolve from propDefinitions or props
     : T extends { propDefinition: readonly [infer App, infer PropName] }
@@ -801,24 +890,69 @@ export type DeriveAppInstance<T> =
         { [K in keyof T as K extends "props" | "propDefinitions" | "methods" ? never : K]: T[K] }
     >;
 
+/** True when a prop definition resolves to `$.interface.http` (runtime-only on `run`). */
+type IsHttpInterfacePropDef<P> =
+    P extends { type: '$.interface.http' }
+    ? true
+    : P extends { propDefinition: readonly [infer App, infer PropName] }
+    ? App extends { propDefinitions: Record<string, any> }
+        ? PropName extends keyof App['propDefinitions']
+            ? App['propDefinitions'][PropName] extends { type: '$.interface.http' }
+                ? true
+                : false
+            : false
+        : App extends { props: Record<string, any> }
+            ? PropName extends keyof App['props']
+                ? App['props'][PropName] extends { type: '$.interface.http' }
+                    ? true
+                    : false
+                : false
+            : false
+    : false;
+
 export type DeriveSignalInstance<T> =
     Spread<
-        Omit<T, "props" | "propDefinitions" | "methods"> &
+        Omit<T, SignalInstanceExcludedKeys> &
         (T extends { props: Record<string, any> }
-            ? { [K in keyof T["props"]]: PropType<T["props"][K]> }
+            ? { [K in keyof T['props']]: PropType<T['props'][K]> }
             : {}) &
         (T extends { propDefinitions: Record<string, any> }
-            ? { [K in keyof T["propDefinitions"]]: PropType<T["propDefinitions"][K]> }
+            ? { [K in keyof T['propDefinitions']]: PropType<T['propDefinitions'][K]> }
             : {}) &
-        // Add $emit to all signal instances
         EmitFunction &
         (T extends { methods: Record<string, any> }
-            ? { [K in keyof T["methods"]]: T["methods"][K] }
+            ? { [K in keyof T['methods']]: T['methods'][K] }
             : {}) &
-        // Also include all direct methods on the object
-        { [K in keyof T as K extends "props" | "propDefinitions" | "methods" ? never : K]: T[K] }
+        {
+            [K in keyof T as K extends SignalInstanceExcludedKeys ? never : K]: T[K];
+        }
     >;
 
+/** Module definition keys that are not instance fields on `this` in `run` or hooks. */
+type SignalInstanceExcludedKeys =
+    | 'props'
+    | 'propDefinitions'
+    | 'methods'
+    | 'run'
+    | 'hooks';
+
+/** Prop names on `T` that are `$.interface.http` (excluded from hook `this`). */
+type HttpInterfacePropKeys<T> =
+    T extends { props: infer P extends Record<string, unknown> }
+        ? keyof {
+              [K in keyof P as IsHttpInterfacePropDef<P[K]> extends true ? K : never]: true;
+          }
+        : never;
+
+/**
+ * `this` inside signal hooks: instance props minus `$.interface.http` and `$emit`.
+ * Use `params.$.http.configureResponseCaching` in `save`.
+ */
+export type DeriveSignalHookInstance<T> = Omit<
+    DeriveSignalInstance<T>,
+    HttpInterfacePropKeys<T> | keyof EmitFunction
+>;
+
 // In your element-types
 export type PropDefinitionType<App, PropName extends string> =
     App extends { propDefinitions: Record<string, any> }
@@ -827,21 +961,37 @@ export type PropDefinitionType<App, PropName extends string> =
     : unknown
     : unknown;
 
-// --- Add this helper above DeriveActionInstance ---
-
-// Enhanced action instance type
+/** Module definition keys that are not instance fields on `this` in `run`. */
+type ActionInstanceExcludedKeys =
+    | 'props'
+    | 'propDefinitions'
+    | 'methods'
+    | 'run'
+    | 'type'
+    | 'name'
+    | 'description'
+    | 'icon'
+    | 'noAuth'
+    | 'slots'
+    | 'hasNew'
+    | 'initValue';
+
+/** Runtime `this` for action `run` (prop values via {@link PropType}, including embedded apps). */
 export type DeriveActionInstance<T> =
     Spread<
-        Omit<T, "props" | "propDefinitions" | "methods"> &
+        Omit<T, ActionInstanceExcludedKeys> &
         (T extends { props: Record<string, any> }
-            ? { [K in keyof T["props"]]: PropType<T["props"][K]> }
+            ? { [K in keyof T['props']]: PropType<T['props'][K]> }
             : {}) &
         (T extends { propDefinitions: Record<string, any> }
-            ? { [K in keyof T["propDefinitions"]]: PropType<T["propDefinitions"][K]> }
+            ? { [K in keyof T['propDefinitions']]: PropType<T['propDefinitions'][K]> }
             : {}) &
         (T extends { methods: Record<string, any> }
-            ? { [K in keyof T["methods"]]: T["methods"][K] }
-            : {})
+            ? { [K in keyof T['methods']]: T['methods'][K] }
+            : {}) &
+        {
+            [K in keyof T as K extends ActionInstanceExcludedKeys ? never : K]: T[K];
+        }
     >;
 
 // Helper type to create a module with proper this context
@@ -878,7 +1028,10 @@ export type ActionInstance<A extends Action> = DeriveActionInstance<A>;
 export type SignalInstance<S extends Signal> = DeriveSignalInstance<S>;
 
 export type SignalMethod<S extends Signal> = (this: SignalInstance<S>, params: SignalRunOptions) => Promise<unknown>;
-export type ActionMethod<A extends Action> = (this: ActionInstance<A>, params: { $: any }) => Promise<unknown>;
+export type ActionMethod<A extends Action> = (
+    this: ActionInstance<A>,
+    params: ActionRunOptions,
+) => Promise<unknown>;
 
 export type PropStringDefinitionTypes = "text" | "html" | "markdown" | "json" | "xml" | "yaml" | "csv" | "tsv" | "css" | "sql" | "email" | "emailList" | "urlList" | "url" | "base64" | "javascript";
 
@@ -905,22 +1058,112 @@ export function defineApp<const T extends object>(app: T & ThisType<DeriveAppIns
     return app;
 }
 
-// Helper to provide ThisType context for action definitions
-export function defineAction<const T extends
-    { props?: Record<string, unknown> } &
-    { type: "action" } &
-    { name?: string } &
-    { description?: string } &
-    { icon?: ElementIcon } &
-    { noAuth?: boolean } &
-    { slots?: ISlotDefinition } &
-    { methods?: Record<string, (...args: any[]) => any> } &
-    { hasNew?: boolean } &
-    { initValue?: any }>(action: T & ThisType<DeriveActionInstance<T>>): T {
+export type ActionRunFn = (params: ActionRunOptions) => void | Promise<unknown>;
+
+/** Canonical action entrypoint — implement `run` here (see process-internal loop, etc.). */
+export type ActionMethodsRun = {
+    methods: Record<string, unknown> & { run: ActionRunFn };
+};
+
+/**
+ * @deprecated Use `methods: { run }` instead of a top-level `run` property.
+ * Runtime still accepts this shape via `restructureElement`.
+ */
+export type ActionMethodsLegacyTopLevelRun = {
+    /** @deprecated Use `methods.run`. */
+    run?: ActionRunFn;
+};
+
+/** Minimum shape for {@link defineAction}. Prefer {@link ActionMethodsRun}. */
+export type ActionMethods = ActionMethodsRun | ActionMethodsLegacyTopLevelRun;
+
+/** Structural requirements for an action module (tooling; prefer {@link defineAction}). */
+export type ActionDefinitionShape<T> = {
+    methods: Record<string, unknown> & {
+        run: (this: DeriveActionInstance<T>, params: ActionRunOptions) => Promise<unknown>;
+    };
+    /**
+     * @deprecated Use `methods.run`.
+     */
+    run?: (this: DeriveActionInstance<T>, params: ActionRunOptions) => Promise<unknown>;
+};
+
+/** Contextual `this` for top-level and `methods.*` action functions. */
+export type ActionMethodsWithThis<T> = T &
+    ThisType<DeriveActionInstance<T>> &
+    (T extends { methods?: infer M extends Record<string, unknown> }
+        ? { methods: M & ThisType<DeriveActionInstance<T>> }
+        : {});
+
+export function defineAction<
+    const T extends ActionMethods & { type: 'action' } & Record<string, unknown>,
+>(action: ActionMethodsWithThis<T>): T {
     return action;
 }
 
-export function defineSignal<const T extends { run: (params: SignalRunOptions) => Promise<unknown> }>(signal: T & ThisType<DeriveSignalInstance<T>>): T {
+/** `params.$` for `hooks.activate` / `hooks.deactivate`. */
+export type SignalHostHookParameters = {
+    $: SignalLifecycleHookHostServices;
+};
+
+/** `params.$` for `hooks.save` — publish-only; not {@link SignalRunHostServices}. */
+export type SignalSaveHostParameters = {
+    $: SignalSaveHookHostServices;
+};
+
+export type SignalHostHookMethod<T> = (
+    this: DeriveSignalHookInstance<T>,
+    params: SignalHostHookParameters,
+) => void | Promise<void>;
+
+export type SignalSaveHookMethod<T> = (
+    this: DeriveSignalHookInstance<T>,
+    params: SignalSaveHostParameters,
+) => void | Promise<void>;
+
+export type SignalHooksDefinition<T> = {
+    deactivate?: SignalHostHookMethod<T>;
+    activate?: SignalHostHookMethod<T>;
+    save?: SignalSaveHookMethod<T>;
+    onDeactivate?: SignalHostHookMethod<T>;
+    onActivate?: SignalHostHookMethod<T>;
+    onSave?: SignalSaveHookMethod<T>;
+};
+
+/**
+ * Hook implementations for {@link defineSignal}: `params.$` is typed here; `this` comes from
+ * {@link ThisType}<{@link DeriveSignalHookInstance}<T>> (avoids circular `T` and empty `this`).
+ */
+export type SignalHooksContextualDefinition = {
+    deactivate?: (params: SignalHostHookParameters) => void | Promise<void>;
+    activate?: (params: SignalHostHookParameters) => void | Promise<void>;
+    save?: (params: SignalSaveHostParameters) => void | Promise<void>;
+    onDeactivate?: (params: SignalHostHookParameters) => void | Promise<void>;
+    onActivate?: (params: SignalHostHookParameters) => void | Promise<void>;
+    onSave?: (params: SignalSaveHostParameters) => void | Promise<void>;
+};
+
+/** Hook bag for {@link defineSignal}. */
+export type SignalHooksWithThis<T> = SignalHooksContextualDefinition &
+    ThisType<DeriveSignalHookInstance<T>>;
+
+/** Structural requirements for a signal module (used by tooling; prefer {@link defineSignal}). */
+export type SignalDefinitionShape<T> = {
+    run: (this: DeriveSignalInstance<T>, params: SignalRunOptions) => Promise<unknown>;
+    hooks?: SignalHooksDefinition<T>;
+};
+
+/** @deprecated Use {@link defineSignal} — kept for generated lib compatibility. */
+export type SignalMethods = {
+    run: (params: SignalRunOptions) => Promise<unknown>;
+};
+
+export function defineSignal<const T extends SignalMethods & Record<string, unknown>>(
+    signal: T &
+        ThisType<DeriveSignalInstance<T>> & {
+            hooks?: SignalHooksWithThis<T>;
+        },
+): T {
     return signal;
 }
 

package/src/resolve-signal-hook-is-draft.spec.ts

@@ -0,0 +1,13 @@
+import { resolveSignalHookIsDraft } from './index';
+
+describe('resolveSignalHookIsDraft', () => {
+    it('uses explicit isDraft when set', () => {
+        expect(resolveSignalHookIsDraft({ isDraft: true, executionContext: 'production' })).toBe(true);
+        expect(resolveSignalHookIsDraft({ isDraft: false, executionContext: 'editor' })).toBe(false);
+    });
+
+    it('falls back to executionContext editor', () => {
+        expect(resolveSignalHookIsDraft({ executionContext: 'editor' })).toBe(true);
+        expect(resolveSignalHookIsDraft({ executionContext: 'production' })).toBe(false);
+    });
+});