@wippy-fe/types-global-proxy 0.0.31 → 0.0.34

package/index.d.ts

@@ -533,6 +533,46 @@ interface AppConfigOverrides {
     apiRoutes?: ApiRoutesOverride;
 }
 
+/**
+ * Wippy package metadata types.
+ *
+ * **Layer boundary**: package.json is the **FE-author's view**. It is
+ * source-relative and BE/router/FS agnostic. It describes the build
+ * artifact (e.g. `browser: "dist/index.js"`, `wippy.path: "dist/app.html"`)
+ * without knowing where the operator will serve it.
+ *
+ * The YAML registry entry (`wippy/views`) is the **operator's view**. It
+ * is deployment-aware and owns paths that depend on the served layout.
+ * YAML's `meta.entry_point` overrides the bundled wippy.path / browser
+ * when the operator's serving pipeline reshapes the URL space (e.g.
+ * `vite --outDir <static-dir>` flattens away the `dist/` prefix).
+ *
+ * YAML wins on every field. Bundled meta is the fallback. See
+ * `wippy-framework/src/views/README.md` for the per-field mapping table.
+ *
+ * The consumer's `package.json` `wippy` block is the canonical FE-source
+ * declaration. At build time the `@wippy-fe/vite-plugin` plugins resolve
+ * any `file://<relative-path>` references inside the wippy block (file
+ * contents replace the URI string) and emit `dist/wippy-meta.json` with
+ * the resolved package.json.
+ *
+ * `wippy-meta.json` is the MANDATORY contract between consumers and
+ * `wippy/views` ≥ 0.5.0. Without it, `views` falls back to its legacy
+ * YAML-synthesis path (deprecated; exists only for migration). See
+ * `web_components.spec.md` § "Package metadata: source of truth".
+ *
+ * Convention for `file://`-referenced files: name them
+ * `<field-name-kebab>.do-not-link.<ext>` — the basename IS the kebab-case
+ * spelling of the wippy block field the file populates. Examples:
+ *   - `wippy.configOverrides.customization.customCSS` → `custom-css.do-not-link.css`
+ *   - `wippy.description` → `description.do-not-link.md`
+ *   - `wippy.<future-field>` → `<future-field-kebab>.do-not-link.<ext>`
+ * The `.do-not-link.` infix is an imperative directive that consistently
+ * prevents AI agents from `<link>`/`<script>`-ing the file directly in
+ * app.html — empirically verified via blind tests. The proxy injects the
+ * file's content at runtime from the resolved package metadata.
+ */
+
 interface ProxyConfig {
     enabled: boolean;
     injections: {
@@ -559,6 +599,15 @@ interface SanitizeOptions {
     extraTags?: Record<string, string[]>;
 }
 
+interface BridgeRequestOptions {
+    timeoutMs?: number;
+}
+interface ProxyBridgeApi {
+    post: (channel: string, payload?: unknown) => void;
+    request: <T = unknown>(channel: string, payload?: unknown, options?: BridgeRequestOptions) => Promise<T>;
+    on: (channel: string, handler: (payload: unknown) => unknown | Promise<unknown>) => () => void;
+}
+
 declare namespace UploadApi {
     interface Meta {
         filename: string;
@@ -1125,6 +1174,19 @@ type Events = {
 };
 declare function createEvents(): <T extends string>(topicPattern: T, callback: T extends KnownTopics ? Events[T] : Events["@message"]) => nanoevents.Unsubscribe;
 
+interface HtmlInjectOptions {
+    baseUrl?: string;
+    resourceId?: string;
+    resourceType?: AppConfig['context']['resourceType'];
+    route?: string;
+    isNavOwner?: boolean;
+    configOverrides?: AppConfigOverrides;
+    proxyConfig?: ProxyConfig;
+}
+interface ProxyHtmlApi {
+    inject: (sourceHtml: string, options?: HtmlInjectOptions) => Promise<string>;
+}
+
 /**
  * Link classifier — decides whether an href targets:
  *   - `host-nav`    host-level route claimed by a view page or system route
@@ -1280,6 +1342,7 @@ interface ProxyApiInstance {
          * host will be dropped silently by the parent.
          */
         layout: LayoutApi;
+        bridge: ProxyBridgeApi;
         logout: () => void;
     };
     api: AxiosInstance;
@@ -1302,6 +1365,7 @@ interface ProxyApiInstance {
     logger: LoggerApi;
     state: StateApi;
     ws: ProxyWsApi;
+    html: ProxyHtmlApi;
     loadWebComponent: (componentId: string, tagName?: string) => Promise<void>;
     /**
      * Resolve a registered `view.component`'s custom-element tag name to its
@@ -1390,6 +1454,7 @@ declare global {
             loadWebComponent: () => Promise<ProxyApiInstance['loadWebComponent']>;
             loadByTagName: () => Promise<ProxyApiInstance['loadByTagName']>;
             sanitize: () => Promise<ProxyApiInstance['sanitize']>;
+            html: () => Promise<ProxyApiInstance['html']>;
         };
         tailwind?: {
             config: Partial<typeof _default>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wippy-fe/types-global-proxy",
-  "version": "0.0.31",
+  "version": "0.0.34",
   "description": "Global type declarations for Wippy iframe proxy (window.getWippyApi, $W, etc.)",
   "license": "UNLICENSED",
   "types": "index.d.ts"