@wippy-fe/types-global-proxy 0.0.30 → 0.0.32

package/index.d.ts

@@ -284,6 +284,7 @@ interface ApiRoutes {
     };
     components: {
         list: string;
+        byTag: string;
     };
     tools: {
         byName: string;
@@ -532,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: {
@@ -553,6 +594,11 @@ interface ProxyConfig {
     };
 }
 
+interface SanitizeOptions {
+    /** Tags + attrs allowed on top of defaults + the runtime allowlist. */
+    extraTags?: Record<string, string[]>;
+}
+
 declare namespace UploadApi {
     interface Meta {
         filename: string;
@@ -1297,6 +1343,28 @@ interface ProxyApiInstance {
     state: StateApi;
     ws: ProxyWsApi;
     loadWebComponent: (componentId: string, tagName?: string) => Promise<void>;
+    /**
+     * Resolve a registered `view.component`'s custom-element tag name to its
+     * module URL via the views API and define it on `customElements`. Use this
+     * instead of hardcoding peer-module URLs from a consumer WC. Idempotent.
+     *
+     * `options.timeoutMs` overrides the default 30s deadline for waiting on
+     * `customElements.define` after the script is appended — useful when a
+     * caller wants a faster failure (e.g. probing whether a component exists).
+     */
+    loadByTagName: (tag: string, options?: {
+        timeoutMs?: number;
+    }) => Promise<void>;
+    /**
+     * Default-allowlisted HTML sanitizer scoped to this runtime. Combines
+     * `defaultAllowedTags` / `defaultAllowedAttributes` with the set of
+     * web-component tags currently registered in this proxy context — so
+     * a child app calling `loadByTagName('w-foo')` and then
+     * `$W.sanitize('<w-foo>...</w-foo>')` gets the tag preserved without
+     * having to re-declare the allowlist. See `SanitizeOptions` for
+     * per-call overrides.
+     */
+    sanitize: (html: string, opts?: SanitizeOptions) => string;
 }
 
 declare global {
@@ -1360,6 +1428,8 @@ declare global {
             state: () => Promise<ProxyApiInstance['state']>;
             ws: () => Promise<ProxyApiInstance['ws']>;
             loadWebComponent: () => Promise<ProxyApiInstance['loadWebComponent']>;
+            loadByTagName: () => Promise<ProxyApiInstance['loadByTagName']>;
+            sanitize: () => Promise<ProxyApiInstance['sanitize']>;
         };
         tailwind?: {
             config: Partial<typeof _default>;

package/package.json

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