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

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: {

package/package.json

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