import { MutateStoragePayload } from "./block_storage.js"; import { ConfigRenderLambda } from "./bconfig/lambdas.js"; import "./bconfig/index.js"; import { ArgsIssue, StringifiedJson } from "@milaboratories/pl-model-common"; /** * The current facade version. This value is used for `requiresModelAPIVersion` * feature flag in BlockModelV3. */ export declare const BLOCK_STORAGE_FACADE_VERSION = 2; /** * All facade callback names as constants. * These are the source of truth - the interface is derived from these. * * IMPORTANT: When adding a new callback: * 1. Add the constant here * 2. Add the callback signature to FacadeCallbackTypes below * 3. The BlockStorageFacade type will automatically include it */ export declare const BlockStorageFacadeCallbacks: { readonly StorageApplyUpdate: "__pl_storage_applyUpdate"; readonly StorageDebugView: "__pl_storage_debugView"; readonly StorageMigrate: "__pl_storage_migrate"; readonly ArgsDerive: "__pl_args_derive"; readonly PrerunArgsDerive: "__pl_prerunArgs_derive"; readonly StorageInitial: "__pl_storage_initial"; readonly InitializationParamsDerive: "__pl_initializationParams_derive"; readonly StorageInitialFromParams: "__pl_storage_initialFromParams"; readonly InitializationParamsValidate: "__pl_initializationParams_validate"; }; /** * Lambda handles for facade callbacks. * Used by the middle layer to invoke callbacks via executeSingleLambda(). */ export declare const BlockStorageFacadeHandles: { __pl_args_derive: ConfigRenderLambda; __pl_initializationParams_derive: ConfigRenderLambda; __pl_initializationParams_validate: ConfigRenderLambda; __pl_prerunArgs_derive: ConfigRenderLambda; __pl_storage_applyUpdate: ConfigRenderLambda; __pl_storage_debugView: ConfigRenderLambda; __pl_storage_initial: ConfigRenderLambda; __pl_storage_initialFromParams: ConfigRenderLambda; __pl_storage_migrate: ConfigRenderLambda; }; /** * The complete facade interface between bundled blocks (SDK) and middle layer. * * This interface defines ALL callbacks that a block registers. The middle layer * calls these callbacks to perform storage operations. * * ALL types are inlined to simplify versioning - when a callback changes, * the entire signature is visible in one place. * * BACKWARD COMPATIBILITY: * - This interface can only be EXTENDED, never shrunk * - Existing callback signatures MUST NOT change * - Middle layer should use Partial when dealing with * blocks of unknown version (older blocks may not have all callbacks) * * Each callback is documented with: * - Purpose and when it's called * - Parameter descriptions * - Return value description */ export interface BlockStorageFacade { /** * Apply state update to storage. * Called when UI updates block state (setState) or plugin data. * @param currentStorageJson - Current storage as JSON string * @param payload - Update payload with operation type and value * @returns Updated storage as JSON string */ [BlockStorageFacadeCallbacks.StorageApplyUpdate]: (currentStorageJson: StringifiedJson, payload: MutateStoragePayload) => StringifiedJson; /** * Get debug view of storage. * Called by developer tools to inspect storage state. * @param storageJson - Storage as JSON string (or undefined for new blocks) * @returns JSON string containing StorageDebugView */ [BlockStorageFacadeCallbacks.StorageDebugView]: (storageJson: StringifiedJson | undefined) => StringifiedJson; /** * Run storage migration. * Called when block loads to migrate data to latest version. * @param currentStorageJson - Current storage as JSON string (or undefined for new blocks) * @returns Migration result - either error or success with new storage */ [BlockStorageFacadeCallbacks.StorageMigrate]: (currentStorageJson: StringifiedJson | undefined) => { error: string; } | { error?: undefined; newStorageJson: StringifiedJson; info: string; }; /** * Derive args from storage. * Called to get block configuration args from storage, and whether the block may run them. * * A middle layer that predates args issues reads only `error` and `value`, and each variant * means the same to it as before: `value` is runnable args, `error` is no args. A block built * with an SDK that predates args issues returns `{ error }` or `{ value }` with no `issues`. * * @param storageJson - Storage as JSON string * @returns One of: * - `{ error }`: `args()` threw, so there are no args; * - `{ error, args, issues }`: args were built, but the block's `argsIssues()` found errors in * them, so the block must not run; `error` joins the error messages, `issues` lists every * issue; * - `{ value, issues }`: args the block may run; `issues` holds the warnings. */ [BlockStorageFacadeCallbacks.ArgsDerive]: (storageJson: StringifiedJson) => { error: string; } | { error: string; args: unknown; issues: ArgsIssue[]; } | { error?: undefined; value: unknown; issues: ArgsIssue[]; }; /** * Derive prerunArgs from storage. * Called to get prerun args; falls back to args callback if not registered. * * A block with its own prerunArgs is staged with them unless its `prerunArgsIssues()` finds errors * in them. A block without its own prerunArgs is staged with its args unless its `argsIssues()` * finds errors in them. * * A middle layer that predates args issues reads only `error` and `value`: `value` is args to * stage, `error` skips staging. A block built with an SDK that predates args issues returns * `{ error }` or `{ value }` with no `issues`. * * @param storageJson - Storage as JSON string * @returns One of: * - `{ error }`: the lambda building the prerun args threw; * - `{ error, issues }`: prerun args were built, but errors were found in them, so the block * is not staged; `error` joins the error messages, `issues` lists every issue; * - `{ value, issues }`: args to stage, `undefined` to skip staging; `issues` holds the * warnings. */ [BlockStorageFacadeCallbacks.PrerunArgsDerive]: (storageJson: StringifiedJson) => { error: string; } | { error: string; issues: ArgsIssue[]; } | { error?: undefined; value: unknown; issues: ArgsIssue[]; }; /** * Get initial storage JSON for new blocks. * Called when creating a new block to get complete initial storage. * @returns Initial storage as JSON string */ [BlockStorageFacadeCallbacks.StorageInitial]: () => StringifiedJson; /** * Derive this block's template entry params from storage. * Called when exporting the project as a template. * * Every V3 block declares `.templateParams()` — the model does not build without * it — so every export produces params. A block whose state carries nothing worth * restoring returns `{}`, which is written out and used as-is by init. * * The returned params are written out exactly as they come back, references included: the * template engine carrying them recognizes nothing in there, and the block that receives * them on the way back in is what repoints them. The caller supplies everything else in the * entry — `id`, `kind` — so the lambda cannot set them. * * @param storageJson - Storage as JSON string * @returns Either an error, or the params to write */ [BlockStorageFacadeCallbacks.InitializationParamsDerive]: (storageJson: StringifiedJson) => { error: string; } | { error?: undefined; value: unknown; }; /** * Get initial storage JSON for a block created from params. * Called when applying a template, once per entry that carries `params`. * * The mirror image of {@link BlockStorageFacadeCallbacks.InitializationParamsDerive}: * that one turns storage into params, this one turns params into storage. Every * applied entry comes through here, including one whose file omitted `params` — * an omitted key is read as `{}` and checked like any other value, so no entry * reaches a block without passing its kind's contract. * {@link BlockStorageFacadeCallbacks.StorageInitial} stays the UI-creation path, * where there are genuinely no params. * * Separate from `StorageInitial` rather than an optional argument to it, * deliberately: a block bundled with an older SDK does not register this * callback at all, so the caller sees it missing and can say so. Widening * `StorageInitial` would instead have that block silently ignore the params and * produce a default-initialized block that looks successfully applied. * * The params arrive as ordinary live params — references are `PlRef`s, already * pointing at the ids the target project just assigned. Resolution happens in * the engine, before this call, so a block's init factory never handles a * template-local reference. * * Errors are returned, not thrown: a factory rejecting params it cannot use is * an expected outcome for a hand-written template file, and every entry's * problem is reported together. * * **Also where the entry's references are pointed at this project.** Params reach here * exactly as the file held them: nothing between the block that exported them and this call * marks a reference, reads one, or rewrites one, because recognizing one means knowing the * reference system and this bundle is where that knowledge lives. `blockIdsJson` maps each * template-local entry id to the block id it was given, holding the entries created so far — * so an id it does not name is left alone, and a reference to an entry created later names * nothing rather than naming the wrong block. * * Relocating and initializing are one call rather than two because every call * re-instantiates the runtime and re-evaluates the whole model bundle: splitting them would * parse the block twice per entry to produce an intermediate only the second half reads. * * @param paramsJson - The entry's params as JSON string, as the file held them * @param blockIdsJson - template-local entry id → assigned block id, as a JSON object * @returns Either an error, or the initial storage as JSON string */ [BlockStorageFacadeCallbacks.StorageInitialFromParams]: (paramsJson: StringifiedJson, blockIdsJson: StringifiedJson) => { error: string; } | { error?: undefined; storageJson: StringifiedJson; }; /** * Check params against this block's kind, creating nothing. * * Called once per entry before a template is applied, so params a kind rejects are * reported against the entry that carries them while there is still no project — the * same reason references and ids are checked before construction starts. Applying * without this call is safe but worse: `StorageInitialFromParams` runs the same check * and refuses, by which point earlier entries have already been created. * * A pass carries nothing back but its own absence of error: every kind declares a * parser, so a pass means the params were checked against the contract, not merely * that they were valid JSON. * * Reference ids inside the params may be placeholders at this point: the check runs * before blocks exist, so what is verified is the shape of the params, not what they * point at. * * @param paramsJson The entry's params as JSON string * @returns Why the params were rejected, or nothing */ [BlockStorageFacadeCallbacks.InitializationParamsValidate]: (paramsJson: StringifiedJson) => { error: string; } | { error?: undefined; }; } /** Register all facade callbacks at once. Ensures all required callbacks are provided. */ export declare function registerFacadeCallbacks(callbacks: BlockStorageFacade): void; //# sourceMappingURL=block_storage_facade.d.ts.map