@powerhousedao/builder-tools 6.2.3-dev.5 → 6.2.3-dev.50

package/dist/index.d.mts

@@ -1,17 +1,17 @@
+import { DYNAMIC_BASE_PLACEHOLDER } from "@powerhousedao/shared/connect";
 import { CommonServerOptions, HtmlTagDescriptor, InlineConfig, Plugin } from "vite";
 import { PowerhouseConfig, PowerhousePackage } from "@powerhousedao/config";
-import { PHConnectRuntimeConfig } from "@powerhousedao/shared/clis";
-
+import { PHConnectRuntimeConfig, PowerhouseConfig as PowerhouseConfig$1 } from "@powerhousedao/shared/clis";
 //#region connect-utils/constants.d.ts
-declare const EXTERNAL_PACKAGES_IMPORT = "PH:EXTERNAL_PACKAGES";
-declare const IMPORT_SCRIPT_FILE = "external-packages.js";
-declare const LOCAL_PACKAGE_ID = "ph:local-package";
-declare const PH_DIR_NAME = ".ph";
+export declare const EXTERNAL_PACKAGES_IMPORT = "PH:EXTERNAL_PACKAGES";
+export declare const IMPORT_SCRIPT_FILE = "external-packages.js";
+export declare const LOCAL_PACKAGE_ID = "ph:local-package";
+export declare const PH_DIR_NAME = ".ph";
 //#endregion
 //#region connect-utils/vite-plugins/build-hash.d.ts
 /** Name of the build-identity file emitted into the build output. */
-declare const BUILD_HASH_FILE: "build-hash.json";
-interface BuildHashInput {
+export declare const BUILD_HASH_FILE: "build-hash.json";
+export interface BuildHashInput {
   /** Monorepo workspace git SHA (CI/dev builds); empty outside the monorepo. */
   workspaceGitSha: string;
   /** Monorepo workspace version (CI/dev builds); empty outside it. */
@@ -38,8 +38,8 @@ interface BuildHashInput {
  * (define `PH_CONNECT_BUILD_HASH`) to `build-hash.json`, which the build
  * emits alongside the app and the server must serve no-cache.
  */
-declare function computeBuildHash(input: BuildHashInput): string;
-declare function buildHashFromBuildOptions(options: {
+export declare function computeBuildHash(input: BuildHashInput): string;
+export declare function buildHashFromBuildOptions(options: {
   dirname: string;
   phConfig: unknown;
   packages: ReadonlyArray<{
@@ -57,13 +57,13 @@ declare function buildHashFromBuildOptions(options: {
  * Build-only: dev (studio) never runs generateBundle, and the SPA check
  * treats a missing file as "nothing to compare" and stays silent.
  */
-declare function connectBuildHashPlugin(buildHash: string): Plugin;
+export declare function connectBuildHashPlugin(buildHash: string): Plugin;
 //#endregion
 //#region connect-utils/externalize-vendor.d.ts
-interface VendorPrebuildOptions {
-  /** Project root (the reactor-project dir). */
+export interface VendorPrebuildOptions {
+  /** Project root the vendor deps resolve from. */
   dirname: string;
-  /** Bare specifiers to bundle into the vendor (defaults to the heavy libs). */
+  /** Specifiers to prebuild into the vendor (defaults to the dev set). */
   include?: string[];
   /** Specifiers left external to the build (defaults to the React family). */
   external?: string[];
@@ -73,35 +73,305 @@ interface VendorPrebuildOptions {
   errorRef?: {
     message?: string;
   };
+  /**
+   * The APP's base — the same string the app build uses (the dynamic-base
+   * placeholder, or a normalized deploy base like "/app/"). The vendor's own
+   * build base is this plus the vendor segment, so emitted asset URLs land
+   * under <app-base>__vendor__/. Default: the dynamic placeholder + segment
+   * (dev behavior). Import-map values stay base-relative; the production
+   * build strips the leading slash (values then resolve against the page URL
+   * under any deploy base), the dev flow prefixes its own base.
+   */
+  base?: string;
+  /** NODE_ENV define for the vendor build (default "development"). */
+  nodeEnv?: "development" | "production";
 }
 /**
  * The stable Connect libraries worth prebuilding. The React family is NOT here —
  * it's externalized from the build (see `VENDOR_EXTERNAL`) so the vendor shares
  * the dev server's single React instance via the import map.
  */
-declare const DEFAULT_VENDOR_INCLUDE: string[];
+export declare const DEFAULT_VENDOR_INCLUDE: string[];
 /**
  * React-family specifiers kept external to the vendor build. The vendor's chunks
  * emit bare imports for these; `devReactImportmapPlugin`'s import map resolves
  * them to Vite's pre-bundled React, so there is exactly one React instance.
  */
-declare const VENDOR_EXTERNAL: string[];
-interface PrebuiltVendor {
+export declare const VENDOR_EXTERNAL: string[];
+export interface PrebuiltVendor {
   vendorDir: string;
-  /** import map: bare specifier -> "/__vendor__/<entry>.js". */
+  /** import map: bare specifier -> "/__vendor__/<entry>.js" (base-relative). */
   imports: Record<string, string>;
+  /** Resolved versions of every included + external package. */
+  versions: Record<string, string>;
 }
 /** URL prefix the vendor bundle is served under by the dev middleware. */
-declare const VENDOR_URL_PREFIX = "/__vendor__/";
+export declare const VENDOR_URL_PREFIX = "/__vendor__/";
 /**
  * Build the prebuilt vendor (once, in a throwaway subprocess) and return its dir
  * + import map. Idempotent: reuses a cached vendor built for the same dep set.
  * Returns null on any failure (caller falls back to a normal dev server).
  */
-declare function prebuildConnectVendor(options: VendorPrebuildOptions): Promise<PrebuiltVendor | null>;
+export declare function prebuildConnectVendor(options: VendorPrebuildOptions): Promise<PrebuiltVendor | null>;
+export declare const LOCK_STALE_MS: number;
+export interface VendorLock {
+  dir: string;
+  token: string;
+  timer: ReturnType<typeof setInterval>;
+}
+export declare function acquireLock(lockDir: string): VendorLock | null;
+export declare function releaseLock(lock: VendorLock): void;
+/**
+ * The published specifiers whose entry file the vendor build never emitted.
+ * URLs are base-less (`/__vendor__/x.js`) and resolve inside `vendorDir`.
+ */
+export declare function missingVendorEntries(vendorDir: string, imports: Record<string, string>): {
+  spec: string;
+  url: string;
+}[];
+/**
+ * Rebase the vendor's base-less entry URLs (`/__vendor__/x.js`) onto the
+ * deploy base, so a consumer that resolves them against the page origin lands
+ * under that base rather than the server root. A dynamic-base build keeps its
+ * placeholder, which the runtime substitutes.
+ *
+ * `base` is the app base from `prebuildConnectVendor` callers, but the
+ * VENDOR_DYNAMIC_BASE default already carries the vendor segment — that
+ * trailing segment is dropped first so it is never doubled.
+ */
+export declare function withVendorBase(imports: Record<string, string>, base: string): Record<string, string>;
+//#endregion
+//#region connect-utils/reactor-worker-build.d.ts
+/** URL prefix the worker bundle is served under, next to `__vendor__/`. */
+export declare const REACTOR_WORKER_URL_PREFIX = "/__reactor_worker__/";
+/** Entry filename of the bundle; the tab constructs its SharedWorker from it. */
+export declare const REACTOR_WORKER_ENTRY = "reactor.worker.js";
+/** Content-Type for the extensions the worker build emits; JS is the default. */
+export declare const REACTOR_WORKER_MIME: Record<string, string>;
+export interface ReactorWorkerVendorOptions {
+  /** The vendor's import map (`spec -> /__vendor__/<entry>.js`). */
+  imports: Record<string, string>;
+  /** The built vendor dir, needed to verify which entries are worker-safe. */
+  dir: string;
+}
+export interface ReactorWorkerBuildOptions {
+  /** Project root the worker's dependencies resolve from. */
+  dirname: string;
+  /** Directory to hold the bundle (e.g. `<dist>/__reactor_worker__`). */
+  outDir: string;
+  /**
+   * The prebuilt vendor to share dependencies with. Only the worker-safe
+   * subset of its entries is externalized (see
+   * {@link workerSafeVendorImports}); omit to bundle everything.
+   */
+  vendor?: ReactorWorkerVendorOptions;
+  /**
+   * Worker entry to build. Defaults to the installed Connect dist's
+   * `reactor.worker.js`; tests inject a fixture entry here.
+   */
+  entryPath?: string;
+  /** NODE_ENV define for the build (default "development"). */
+  nodeEnv?: "development" | "production";
+  /** Filled with the failure cause when the prebuild returns null. */
+  errorRef?: {
+    message?: string;
+  };
+}
+export interface PrebuiltReactorWorker {
+  outDir: string;
+  /** Entry filename inside outDir ({@link REACTOR_WORKER_ENTRY}). */
+  entry: string;
+  /**
+   * Digest of everything that shaped this bundle's output (see
+   * {@link computeSourceDigest}); identical for a cache hit and a fresh
+   * build. The dev plugin serves it in `worker-meta.json` next to the
+   * bundle; `apps/connect/src/utils/reactor-worker-url.ts` fetches it to
+   * fold the actual built worker code into the tab's version fingerprint
+   * (W0.6).
+   */
+  sourceDigest: string;
+  /**
+   * The worker-safe vendor subset this bundle externalizes (see
+   * {@link workerSafeVendorImports}); empty without a vendor.
+   */
+  vendorImports: Record<string, string>;
+}
+/**
+ * The installed Connect dist's worker entry, or null when the installed
+ * version predates the worker (the feature is then unavailable, not broken).
+ */
+export declare function resolveReactorWorkerSource(dirname: string): string | null;
+/** `/__vendor__/<entry>.js` -> `../__vendor__/<entry>.js` (sibling dirs). */
+export declare function vendorRelativePath(vendorUrl: string): string;
+/**
+ * Module specifiers a worker cannot resolve: anything that is not relative,
+ * root-relative, or an http(s)/data/blob URL. Used as a post-build guard so a
+ * leftover bare (or `node:`) import fails the build with a name instead of
+ * shipping a worker that dies on its first import statement.
+ *
+ * Expects minified (comment-free) output: a raw-text scan cannot tell a real
+ * import from a JSDoc code sample, and unminified kysely/viem are full of the
+ * latter. The build below always minifies for exactly this reason.
+ */
+export declare function findDisallowedSpecifiers(code: string): string[];
+/**
+ * Packages whose BUILT dist shapes the worker bundle's output even when
+ * connect's own dist/reactor.worker.js entry file did not change.
+ *
+ * That entry is a library artifact whose bare imports this build resolves
+ * through node_modules at BUILD time, so a rebuilt dist anywhere in its
+ * closure changes the bundle output without touching the entry file's own
+ * size/mtime. The list is DERIVED from the installed Connect's own
+ * dependencies rather than hardcoded: the bundle pulls `@renown/sdk`,
+ * `@powerhousedao/powerhouse-vetra-packages` and `@powerhousedao/shared` out
+ * of node_modules too, and a hardcoded pair left every one of those able to be
+ * rebuilt behind a cache hit. Connect's dependency list is the cheap stand-in
+ * for the resolved bundle graph: every workspace package the worker can reach
+ * is reachable through it, and a package not in the bundle only costs a readdir.
+ */
+export declare function upstreamWorkerPackages(dirname: string): string[];
+/**
+ * This module's own installed version, read by walking up from its file to
+ * the nearest `package.json` named "@powerhousedao/builder-tools" (same
+ * technique as `build-hash.ts`'s `readConnectVersion`: builder-tools'
+ * `exports` map has no `./package.json` subpath, so node resolution can't
+ * get there). Works whether this runs from source (tests, this monorepo) or
+ * the built dist.
+ */
+export declare function resolveOwnPackageVersion(): string;
+/**
+ * This package's own version, computed once. Folded into the worker bundle
+ * cache key so a builder-tools release — which can change how the bundle is
+ * built (anything in this module beyond {@link WORKER_BUILD_WORKER} itself,
+ * e.g. `workerSafeVendorImports`, the resolve plugin) — invalidates bundles
+ * a prior builder-tools version cached.
+ */
+export declare const BUILDER_TOOLS_VERSION: string;
+/**
+ * A workspace package's real directory, resolved the way Node's resolver
+ * would (through `node_modules`), or null when it is not installed (e.g. a
+ * non-monorepo consumer project — graceful, not an error). pnpm's
+ * node_modules symlinks resolve to the real package directory, so this
+ * reflects the monorepo's actual dist state, not a stale symlink target.
+ */
+export declare function resolveWorkspacePackageDir(dirname: string, pkgName: string): string | null;
+/**
+ * Cheap content fingerprint of a directory's immediate files: no file bytes
+ * are read, just each entry's name/size/mtime, so it stays fast even for a
+ * large dist. Sensitive to a rebuild in the common cases: Vite's
+ * content-hashed chunk filenames change the name itself; a stable-named file
+ * (an entry point) changes size or mtime. Bounded (`maxFiles`) so a
+ * pathological directory cannot make this slow — deliberately not a
+ * full-tree hash.
+ *
+ * The names are sorted BEFORE the bound is applied, so the subset the bound
+ * keeps is the same subset on every run: readdir order is unspecified, and
+ * truncating it first made the fingerprint of a directory past the bound a
+ * function of whatever order the filesystem happened to report.
+ */
+export declare function distDirFingerprint(dir: string, maxFiles?: number): string;
+export declare function computeSourceDigest(dirname: string, entryPath: string, vendorDir?: string, builderToolsVersion?: string): string;
+/**
+ * Build the worker bundle (once, in a throwaway subprocess) into `outDir`.
+ * Idempotent: reuses a cached bundle built from the same connect dist, vendor
+ * mapping, and builder logic. Returns null on failure (`errorRef` carries the
+ * cause) or when the installed Connect has no worker entry.
+ */
+export declare function prebuildReactorWorker(options: ReactorWorkerBuildOptions): Promise<PrebuiltReactorWorker | null>;
+/** Replace `outDir` with the finished `tmpDir`, old contents removed last. */
+export declare function publishDirAtomic(tmpDir: string, outDir: string): void;
+/**
+ * Scan the emitted JS files REACHABLE from the entry via import statements
+ * for specifiers a worker cannot resolve. Vendor externals were rewritten to
+ * ../__vendor__/ relative paths, so anything bare that survives in the graph
+ * is a real defect.
+ *
+ * Deliberately a graph walk, not a directory walk: the bundled reactor code
+ * carries `new URL(..., import.meta.url)` references to its node
+ * worker-thread entries (executor/projection workers), which Vite emits as
+ * stray assets full of node-only imports. They are unreachable dead weight in
+ * a browser bundle — the production vendor output tolerates the same files —
+ * and must not fail the build.
+ */
+export declare function findBundleSpecifierOffenders(bundleDir: string, entry?: string): {
+  file: string;
+  specs: string[];
+}[];
+/** The page-only markers present in `code`, in a fixed order. */
+export declare function findWorkerUnsafeMarkers(code: string): string[];
+/**
+ * The subset of the vendor's entries a worker may import.
+ *
+ * The vendor build keeps the React family external: its chunks carry bare
+ * `import "react"` statements that the PAGE resolves through its import map.
+ * A worker resolves no import map, so externalizing a vendor spec whose chunk
+ * closure reaches such an import would kill the worker on its first load —
+ * and the chunk graph is shared across vendor entries, so even a React-free
+ * module (e.g. an rpc subpath) can be entangled with React through a shared
+ * chunk. The vendor is also built for the page: a dynamic-base build rewrites
+ * its asset URLs onto a global only the page sets, and its dynamic imports go
+ * through Vite's preload helper, which needs `document`. Each entry's own
+ * closure inside the vendor dir decides: clean closure, worker-safe; anything
+ * bare or page-only in it (see {@link findWorkerUnsafeMarkers}), or a missing
+ * entry file, bundled into the worker instead.
+ */
+export declare function workerSafeVendorImports(vendorDir: string, vendorImports: Record<string, string>): Record<string, string>;
+/**
+ * Builds arbitrary worker-loadable entries with the worker build config.
+ * Exported for the local-package bundles, which need the same self-contained
+ * output and vendor externalization at a different depth.
+ */
+export declare function runWorkerBuildEntries(dirname: string, outDir: string, entries: Record<string, string>, vendorImports: Record<string, string>, nodeEnv: "development" | "production", vendorPrefix?: string): Promise<{
+  ok: boolean;
+  stderr: string;
+}>;
+//#endregion
+//#region connect-utils/worker-packages-build.d.ts
+/** Served under `<base>__reactor_worker__/packages/`. */
+export declare const WORKER_PACKAGES_MANIFEST = "manifest.json";
+export interface WorkerPackagesBuildOptions {
+  /** Project root the packages resolve from. */
+  dirname: string;
+  /** Local package names (`provider: "local"` in powerhouse.config.json). */
+  packages: string[];
+  /** Directory to hold the bundles (`<dist>/__reactor_worker__/packages`). */
+  outDir: string;
+  /** The prebuilt vendor to share dependencies with, when one was built. */
+  vendor?: ReactorWorkerVendorOptions;
+  /**
+   * The vendor's worker-safe subset, when the caller already computed it
+   * (`PrebuiltReactorWorker.vendorImports`); skips walking the vendor again.
+   */
+  safeVendorImports?: Record<string, string>;
+  nodeEnv?: "development" | "production";
+  errorRef?: {
+    message?: string;
+  };
+}
+export interface WorkerPackageManifestEntry {
+  name: string;
+  version?: string;
+  /** Filename inside outDir, as {@link workerPackageFileName} spells it. */
+  file: string;
+}
+/**
+ * The project's own package name when it ships a models bundle, so a caller
+ * can include it beside the configured `provider: "local"` packages. A vetra
+ * project declares no package entry for itself, yet its models are exactly
+ * the ones the worker is missing.
+ */
+export declare function ownProjectPackage(dirname: string): string | undefined;
+/**
+ * Build each local package's models entry into `outDir` and write the
+ * manifest the tab reads. Returns the manifest entries (empty when no local
+ * package ships a models bundle), or null when the build itself failed -
+ * `errorRef` then carries the cause. Both of those remove `outDir`, so a
+ * previous build's bundles never outlive the packages they came from.
+ */
+export declare function prebuildWorkerPackages(options: WorkerPackagesBuildOptions): Promise<WorkerPackageManifestEntry[] | null>;
 //#endregion
 //#region connect-utils/types.d.ts
-type IConnectOptions = {
+export type IConnectOptions = {
   mode: string;
   dirname: string;
   envDir?: string;
@@ -127,8 +397,18 @@ type IConnectOptions = {
   cliPackageRegistryUrl?: string;
   dynamicBase?: boolean;
   favicon?: string;
+  /**
+   * Production vendor: the prebuilt shared-dependency bundle's import map and
+   * version table (from `prebuildConnectVendor`). When set on a production
+   * build, the shared specifiers are externalized from the app bundle and
+   * merged into the page import map. Build input only.
+   */
+  vendor?: {
+    imports: Record<string, string>;
+    versions: Record<string, string>;
+  };
 };
-type ConnectCommonOptions = {
+export type ConnectCommonOptions = {
   base?: string;
   mode?: string;
   configFile?: string;
@@ -138,71 +418,71 @@ type ConnectCommonOptions = {
   defaultDrivesUrl?: string[];
   drivesPreserveStrategy?: "preserve-all" | "preserve-by-url-and-detach";
 };
-type ViteDevOptions = Pick<CommonServerOptions, "port" | "host" | "open" | "cors" | "strictPort"> & {
+export type ViteDevOptions = Pick<CommonServerOptions, "port" | "host" | "open" | "cors" | "strictPort"> & {
   force?: boolean;
 };
-type ConnectStudioOptions = ConnectCommonOptions & {
+export type ConnectStudioOptions = ConnectCommonOptions & {
   devServerOptions?: ViteDevOptions;
   printUrls?: boolean;
   bindCLIShortcuts?: boolean;
 };
-type ConnectBuildOptions = ConnectCommonOptions & {
+export type ConnectBuildOptions = ConnectCommonOptions & {
   outDir?: string;
 };
-type ConnectPreviewOptions = ConnectCommonOptions & Omit<ViteDevOptions, "cors"> & {
+export type ConnectPreviewOptions = ConnectCommonOptions & Omit<ViteDevOptions, "cors"> & {
   outDir?: string;
   printUrls?: boolean;
   bindCLIShortcuts?: boolean;
 };
 //#endregion
 //#region connect-utils/helpers.d.ts
-declare const DEFAULT_CONNECT_OUTDIR: ".ph/connect-build/dist/";
-declare function resolveViteConfigPath(options: Pick<ConnectCommonOptions, "projectRoot" | "viteConfigFile">): string;
-declare function resolvePackage(packageName: string, root?: string): string;
-declare function resolveConnectPackageJson(root?: string): JSON | null;
+export declare const DEFAULT_CONNECT_OUTDIR: ".ph/connect-build/dist/";
+export declare function resolveViteConfigPath(options: Pick<ConnectCommonOptions, "projectRoot" | "viteConfigFile">): string;
+export declare function resolvePackage(packageName: string, root?: string): string;
+export declare function resolveConnectPackageJson(root?: string): JSON | null;
 /**
  * Finds the dist dir of Connect on the local machine
  */
-declare function resolveConnectBundle(root?: string): string;
-declare function resolveConnectPublicDir(root?: string): string;
+export declare function resolveConnectBundle(root?: string): string;
+export declare function resolveConnectPublicDir(root?: string): string;
 /**
  * Copies the Connect dist dir to the target path
  */
-declare function copyConnect(sourcePath: string, targetPath: string): void;
+export declare function copyConnect(sourcePath: string, targetPath: string): void;
 /**
  * Backs up the index.html file
  *
  * Needed when running the Connect Studio dev server on Windows
  */
-declare function backupIndexHtml(appPath: string, restore?: boolean): void;
-declare function removeBase64EnvValues(appPath: string): void;
-declare function readJsonFile(filePath: string): PowerhouseConfig | null;
+export declare function backupIndexHtml(appPath: string, restore?: boolean): void;
+export declare function removeBase64EnvValues(appPath: string): void;
+export declare function readJsonFile(filePath: string): PowerhouseConfig | null;
 /**
  * Takes a list of Powerhouse project packages and optionally local Powerhouse packages and outputs a js file which exports those packages for use in Connect Studio.
  */
-declare function makeImportScriptFromPackages(args: {
+export declare function makeImportScriptFromPackages(args: {
   packages: string[];
   importStyles?: boolean;
   localJsPath?: string;
   localCssPath?: string;
 }): string;
-declare function ensureNodeVersion(minVersion?: string): void;
-declare function runShellScriptPlugin(scriptName: string, connectPath: string): Plugin;
+export declare function ensureNodeVersion(minVersion?: string): void;
+export declare function runShellScriptPlugin(scriptName: string, connectPath: string): Plugin;
 /**
  * Appends the contents to the <head> tag of the index.html file
  */
-declare function appendToHtmlHead(pathToHtml: string, contents: string): Promise<void>;
+export declare function appendToHtmlHead(pathToHtml: string, contents: string): Promise<void>;
 /**
  * Prepends the contents to the <head> tag of the index.html file
  */
-declare function prependToHtmlHead(pathToHtml: string, contents: string): Promise<void>;
-declare function runTsc(outDir: string): void;
-declare function stripVersionFromPackage(packageName: string): string;
+export declare function prependToHtmlHead(pathToHtml: string, contents: string): Promise<void>;
+export declare function runTsc(outDir: string): void;
+export declare function stripVersionFromPackage(packageName: string): string;
 //#endregion
 //#region connect-utils/runtime-config-schema.d.ts
-declare const RUNTIME_CONFIG_SCHEMA_ID = "https://powerhouse.inc/schemas/powerhouse.config.json";
-declare const RUNTIME_CONFIG_SCHEMA_URL = "https://raw.githubusercontent.com/powerhouse-inc/powerhouse/main/packages/builder-tools/connect-utils/runtime-config.schema.json";
-declare const runtimeConfigSchema: {
+export declare const RUNTIME_CONFIG_SCHEMA_ID = "https://powerhouse.inc/schemas/powerhouse.config.json";
+export declare const RUNTIME_CONFIG_SCHEMA_URL = "https://raw.githubusercontent.com/powerhouse-inc/powerhouse/main/packages/builder-tools/connect-utils/runtime-config.schema.json";
+export declare const runtimeConfigSchema: {
   readonly $schema: "http://json-schema.org/draft-07/schema#";
   readonly $id: "https://powerhouse.inc/schemas/powerhouse.config.json";
   readonly title: "Powerhouse Connect runtime configuration";
@@ -315,6 +595,10 @@ declare const runtimeConfigSchema: {
               readonly description: "Studio mode. Enables builder-only capabilities: Connect loads the vetra package and exposes DocumentModel (and vetra spec types) as creatable documents. Forced on by `ph vetra` / `ph connect studio`; false by default.";
               readonly default: false;
             };
+            readonly workflowsEnabled: {
+              readonly type: "boolean";
+              readonly description: "Powerhouse workflows in Connect. When true the tab loads the @powerhousedao/workflow package (workflow + connection documents, their editors and Workflow Studio) and the reactor worker registers its document models. Falls back to the top-level `workflows.enabled`; set it to override that for Connect. Independent of studioMode. False when neither is set.";
+            };
           };
         };
         readonly ai: {
@@ -406,7 +690,7 @@ declare const runtimeConfigSchema: {
             readonly preserveStrategy: {
               readonly type: "string";
               readonly enum: readonly ["preserve-all", "preserve-by-url-and-detach"];
-              readonly description: "Strategy applied when defaultDrives change between deploys. 'preserve-all' keeps user-added drives untouched; 'preserve-by-url-and-detach' detaches removed default drives. No schema default \u2014 opt-in only.";
+              readonly description: "Strategy applied when defaultDrives change between deploys. 'preserve-all' keeps user-added drives untouched; 'preserve-by-url-and-detach' detaches removed default drives. No schema default — opt-in only.";
             };
             readonly sections: {
               readonly type: "object";
@@ -557,6 +841,32 @@ declare const runtimeConfigSchema: {
             };
           };
         };
+        readonly openPanel: {
+          readonly type: "object";
+          readonly additionalProperties: false;
+          readonly description: "OpenPanel product analytics. Set `clientId` to enable; an empty `clientId` disables it. Events are only sent after the user accepts analytics cookies. Takes precedence over the build-time PH_CONNECT_OPENPANEL_* env vars.";
+          readonly properties: {
+            readonly clientId: {
+              readonly type: "string";
+              readonly description: "OpenPanel client id. Empty string disables OpenPanel entirely.";
+              readonly default: "";
+            };
+            readonly apiUrl: {
+              readonly type: "string";
+              readonly description: "OpenPanel API URL for self-hosted instances (e.g. 'https://openpanel.example/api'). Omit to use OpenPanel's hosted API.";
+            };
+            readonly trackUiEvents: {
+              readonly type: "boolean";
+              readonly description: "Track UI events.";
+              readonly default: true;
+            };
+            readonly trackOperations: {
+              readonly type: "boolean";
+              readonly description: "Track document operations.";
+              readonly default: true;
+            };
+          };
+        };
         readonly instance: {
           readonly type: "object";
           readonly additionalProperties: false;
@@ -570,7 +880,7 @@ declare const runtimeConfigSchema: {
             };
             readonly reactorWorker: {
               readonly type: "boolean";
-              readonly description: "Host the reactor in a shared worker instead of on the main thread. Off by default; the main-thread reactor stays the proven path until cutover is verified.";
+              readonly description: "Host the reactor in a shared worker instead of on the main thread. Off by default; the main-thread reactor stays the proven path until cutover is verified. Packaged deployments load the worker from the prebuilt bundle `ph connect build` emits under __reactor_worker__/ (the dev server builds it lazily at the same path); when that bundle is absent the feature reports itself unavailable instead of starting a worker that cannot load.";
               readonly default: false;
             };
           };
@@ -607,12 +917,24 @@ declare const runtimeConfigSchema: {
                 };
               };
             };
+            readonly createSignaturePolicy: {
+              readonly type: "string";
+              readonly enum: readonly ["legacy", "v2-required"];
+              readonly description: "What new documents are created as. `v2-required` documents accept only v2 action signatures and take content-addressed ids; set `legacy` while any peer Connect syncs with predates them. Existing documents keep their policy.";
+              readonly default: "v2-required";
+            };
+            readonly unsupportedStoredDocuments: {
+              readonly type: "string";
+              readonly enum: readonly ["refuse", "read-only"];
+              readonly description: "What the reactor does when this browser's store holds documents at protocol versions this build does not run. `refuse` fails the boot and names the versions; `read-only` boots and keeps those documents read-only.";
+              readonly default: "refuse";
+            };
           };
         };
         readonly pwa: {
           readonly type: "object";
           readonly additionalProperties: false;
-          readonly description: "Progressive-web-app / service-worker overrides, layered on Connect's built-in PWA defaults at build time. Scalar fields deep-merge (this layer wins); the array members (icons, file_handlers, globs, runtimeCaching and denylist patterns) are additive; maximumFileSizeToCacheInBytes takes the max across contributors. (categories is not set here \u2014 it is derived from the manifest's category field.) Only applied when connect.app.offline is true.";
+          readonly description: "Progressive-web-app / service-worker overrides, layered on Connect's built-in PWA defaults at build time. Scalar fields deep-merge (this layer wins); the array members (icons, file_handlers, globs, runtimeCaching and denylist patterns) are additive; maximumFileSizeToCacheInBytes takes the max across contributors. (categories is not set here — it is derived from the manifest's category field.) Only applied when connect.app.offline is true.";
           readonly properties: {
             readonly manifest: {
               readonly type: "object";
@@ -677,7 +999,7 @@ declare const runtimeConfigSchema: {
                     readonly properties: {
                       readonly accept: {
                         readonly type: "object";
-                        readonly description: "MIME type \u2192 file extensions. Each extension must start with '.'; browsers ignore entries without it.";
+                        readonly description: "MIME type → file extensions. Each extension must start with '.'; browsers ignore entries without it.";
                         readonly additionalProperties: {
                           readonly type: "array";
                           readonly items: {
@@ -862,7 +1184,7 @@ declare const runtimeConfigSchema: {
 };
 //#endregion
 //#region connect-utils/vite-config.d.ts
-declare function getConnectHtmlTags(options?: {
+export declare function getConnectHtmlTags(options?: {
   registryUrl?: string | null;
   injectTo?: HtmlTagDescriptor["injectTo"];
 }): [{
@@ -871,84 +1193,74 @@ declare function getConnectHtmlTags(options?: {
     readonly "http-equiv": "Content-Security-Policy";
     readonly content: `script-src 'self' 'unsafe-inline' 'unsafe-eval'${string}; worker-src 'self' blob:; object-src 'none'; base-uri 'self';`;
   };
-  readonly injectTo: "head" | "body" | "head-prepend" | "body-prepend";
+  readonly injectTo: "body" | "body-prepend" | "head" | "head-prepend";
 }, {
   readonly tag: "meta";
   readonly attrs: {
     readonly property: "og:title";
     readonly content: "Connect";
   };
-  readonly injectTo: "head" | "body" | "head-prepend" | "body-prepend";
+  readonly injectTo: "body" | "body-prepend" | "head" | "head-prepend";
 }, {
   readonly tag: "meta";
   readonly attrs: {
     readonly property: "og:type";
     readonly content: "website";
   };
-  readonly injectTo: "head" | "body" | "head-prepend" | "body-prepend";
+  readonly injectTo: "body" | "body-prepend" | "head" | "head-prepend";
 }, {
   readonly tag: "meta";
   readonly attrs: {
     readonly property: "og:url";
     readonly content: "https://apps.powerhouse.io/powerhouse/connect/";
   };
-  readonly injectTo: "head" | "body" | "head-prepend" | "body-prepend";
+  readonly injectTo: "body" | "body-prepend" | "head" | "head-prepend";
 }, {
   readonly tag: "meta";
   readonly attrs: {
     readonly property: "og:description";
     readonly content: "Navigate your organisation’s toughest operational challenges and steer your contributors to success with Connect. A navigation, collaboration and reporting tool for decentralised and open organisation.";
   };
-  readonly injectTo: "head" | "body" | "head-prepend" | "body-prepend";
+  readonly injectTo: "body" | "body-prepend" | "head" | "head-prepend";
 }, {
   readonly tag: "meta";
   readonly attrs: {
     readonly property: "og:image";
     readonly content: "https://cf-ipfs.com/ipfs/bafkreigrmclndf2jpbolaq22535q2sw5t44uad3az3dpvkzrnt4lpjt63e";
   };
-  readonly injectTo: "head" | "body" | "head-prepend" | "body-prepend";
+  readonly injectTo: "body" | "body-prepend" | "head" | "head-prepend";
 }, {
   readonly tag: "meta";
   readonly attrs: {
     readonly name: "twitter:card";
     readonly content: "summary_large_image";
   };
-  readonly injectTo: "head" | "body" | "head-prepend" | "body-prepend";
+  readonly injectTo: "body" | "body-prepend" | "head" | "head-prepend";
 }, {
   readonly tag: "meta";
   readonly attrs: {
     readonly name: "twitter:image";
     readonly content: "https://cf-ipfs.com/ipfs/bafkreigrmclndf2jpbolaq22535q2sw5t44uad3az3dpvkzrnt4lpjt63e";
   };
-  readonly injectTo: "head" | "body" | "head-prepend" | "body-prepend";
+  readonly injectTo: "body" | "body-prepend" | "head" | "head-prepend";
 }, {
   readonly tag: "meta";
   readonly attrs: {
     readonly name: "twitter:title";
     readonly content: "Connect";
   };
-  readonly injectTo: "head" | "body" | "head-prepend" | "body-prepend";
+  readonly injectTo: "body" | "body-prepend" | "head" | "head-prepend";
 }, {
   readonly tag: "meta";
   readonly attrs: {
     readonly name: "twitter:description";
     readonly content: "Navigate your organisation’s toughest operational challenges and steer your contributors to success with Connect. A navigation, collaboration and reporting tool for decentralised and open organisation.";
   };
-  readonly injectTo: "head" | "body" | "head-prepend" | "body-prepend";
+  readonly injectTo: "body" | "body-prepend" | "head" | "head-prepend";
 }];
-declare function getConnectBaseViteConfig(options: IConnectOptions): InlineConfig;
+export declare function getConnectBaseViteConfig(options: IConnectOptions): InlineConfig;
 //#endregion
 //#region connect-utils/vite-plugins/dynamic-base.d.ts
-/**
- * Placeholder base used when Connect is built in dynamic-base mode. The Vite
- * `base` option is set to this token; this plugin rewrites it in the emitted
- * output so the effective base is resolved at serve time from a global instead
- * of being baked at build time.
- *
- * Trailing slash matches `normalizeBasePath` output, so the token sits in the
- * same syntactic position as a concrete base would.
- */
-declare const DYNAMIC_BASE_PLACEHOLDER = "/__PH_DYNAMIC_BASE__/";
 /**
  * Rewrites the placeholder base in emitted JS chunks to a runtime expression so
  * one built `dist/connect` serves under any subpath. Rolldown-native: per-match
@@ -977,17 +1289,19 @@ declare const DYNAMIC_BASE_PLACEHOLDER = "/__PH_DYNAMIC_BASE__/";
  * they need no rewrite once the stylesheet itself is loaded from the right
  * prefix (which the HTML substitution handles).
  */
-declare function connectDynamicBasePlugin(options?: {
+export declare function connectDynamicBasePlugin(options?: {
   forWorker?: boolean;
   workerStripPrefix?: string;
 }): Plugin;
-declare function escapeForRegExp(s: string): string;
+export declare function escapeForRegExp(s: string): string;
 //#endregion
 //#region connect-utils/vite-plugins/ph-config.d.ts
-type PhConfigPluginOptions = {
+export type PhConfigPluginOptions = {
   packages: PowerhousePackage[];
   projectRoot?: string;
   connect?: PHConnectRuntimeConfig;
+  /** The source's top-level `workflows` block; `connect.app.workflowsEnabled` falls back to it. */
+  workflows?: PowerhouseConfig$1["workflows"];
   /**
    * Project-wide package registry URL — the effective value (CLI override
    * `??` source) the caller has already resolved. Copied verbatim into the
@@ -1002,7 +1316,7 @@ type PhConfigPluginOptions = {
    */
   cliConnectOverride?: PHConnectRuntimeConfig;
 };
-declare function phConfigPlugin(options: PhConfigPluginOptions): Plugin;
+export declare function phConfigPlugin(options: PhConfigPluginOptions): Plugin;
 //#endregion
 //#region connect-utils/vite-plugins/theme-boot.d.ts
 /**
@@ -1010,13 +1324,21 @@ declare function phConfigPlugin(options: PhConfigPluginOptions): Plugin;
  * ph-clint connect proxy) and this plugin both check it, so the script is
  * applied exactly once no matter which layer runs first.
  */
-declare const THEME_BOOT_MARKER = "data-ph-theme-boot";
+export declare const THEME_BOOT_MARKER = "data-ph-theme-boot";
 /**
  * Injects the theme boot script at the top of `<head>` of every emitted
  * index.html, so built Connect apps render the stored theme from first paint
  * without depending on a serve-time injector.
  */
-declare function connectThemeBootPlugin(): Plugin;
+export declare function connectThemeBootPlugin(): Plugin;
+//#endregion
+//#region connect-utils/vite-plugins/vendor-import-map.d.ts
+export type VendorImportMapOptions = {
+  /** bare specifier -> URL (already base-prefixed by the caller). */
+  imports: Record<string, string>;
+};
+export declare function vendorImportMapPlugin(options: VendorImportMapOptions): Plugin;
 //#endregion
-export { BUILD_HASH_FILE, BuildHashInput, ConnectBuildOptions, ConnectCommonOptions, ConnectPreviewOptions, ConnectStudioOptions, DEFAULT_CONNECT_OUTDIR, DEFAULT_VENDOR_INCLUDE, DYNAMIC_BASE_PLACEHOLDER, EXTERNAL_PACKAGES_IMPORT, IConnectOptions, IMPORT_SCRIPT_FILE, LOCAL_PACKAGE_ID, PH_DIR_NAME, PhConfigPluginOptions, PrebuiltVendor, RUNTIME_CONFIG_SCHEMA_ID, RUNTIME_CONFIG_SCHEMA_URL, THEME_BOOT_MARKER, VENDOR_EXTERNAL, VENDOR_URL_PREFIX, VendorPrebuildOptions, ViteDevOptions, appendToHtmlHead, backupIndexHtml, buildHashFromBuildOptions, computeBuildHash, connectBuildHashPlugin, connectDynamicBasePlugin, connectThemeBootPlugin, copyConnect, ensureNodeVersion, escapeForRegExp, getConnectBaseViteConfig, getConnectHtmlTags, makeImportScriptFromPackages, phConfigPlugin, prebuildConnectVendor, prependToHtmlHead, readJsonFile, removeBase64EnvValues, resolveConnectBundle, resolveConnectPackageJson, resolveConnectPublicDir, resolvePackage, resolveViteConfigPath, runShellScriptPlugin, runTsc, runtimeConfigSchema, stripVersionFromPackage };
+export { DYNAMIC_BASE_PLACEHOLDER };
+export {};
 //# sourceMappingURL=index.d.mts.map