@longzai-intelligence-liquid-glass/svg-filter 0.0.1

package/README.md

@@ -0,0 +1,12 @@
+# @longzai-intelligence-liquid-glass/svg-filter
+
+Liquid Glass SVG feDisplacementMap 渲染后端：位移图 + 三通道色散 + edge mask。
+
+## 用法
+
+```bash
+bun run --cwd packages/svg-filter lint      # 代码检查
+bun run --cwd packages/svg-filter typecheck # 类型检查（tsgo）
+bun run --cwd packages/svg-filter test      # 单元测试
+bun run --cwd packages/svg-filter build     # 构建（lzi-builder → dist）
+```

package/dist/index.d.ts

@@ -0,0 +1,273 @@
+import { LiquidGlassParams, LiquidGlassParamsInput, LiquidGlassRenderer, LiquidGlassSize, RendererCapability } from "@longzai-intelligence-liquid-glass/core";
+//#region src/displacement-map.utils.d.ts
+/**
+ * 位移图生成结果
+ */
+type DisplacementMapResult = {
+  /**
+   * PNG data URL（喂给 feImage）
+   */
+  dataUrl: string;
+  /**
+   * 图宽度（px）
+   */
+  width: number;
+  /**
+   * 图高度（px）
+   */
+  height: number;
+  /**
+   * 位移编码范围（px，对应 feDisplacementMap 的 scale）
+   */
+  range: number;
+};
+/**
+ * 生成位移图
+ *
+ * @param params - 液态玻璃参数
+ * @returns 位移图结果；无 DOM canvas 环境返回 null
+ */
+declare function generateDisplacementMap(params: LiquidGlassParams): DisplacementMapResult | null;
+//#endregion
+//#region src/filter-graph.utils.d.ts
+/**
+ * filter 图构建选项
+ */
+type FilterGraphOptions = {
+  /**
+   * filter 元素 id
+   */
+  filterId: string;
+  /**
+   * 位移图
+   */
+  map: DisplacementMapResult;
+  /**
+   * 液态玻璃参数
+   */
+  params: LiquidGlassParams;
+};
+/**
+ * 构建 filter 图 markup
+ *
+ * @param options - 构建选项
+ * @returns `<filter>…</filter>` markup 字符串
+ */
+declare function buildFilterMarkup(options: FilterGraphOptions): string;
+/**
+ * 描述 filter 链的原语序列（供测试与能力报告）
+ *
+ * @param params - 液态玻璃参数
+ * @returns 原语类型序列
+ */
+declare function describeFilterChain(params: LiquidGlassParams): string[];
+//#endregion
+//#region src/elasticity.utils.d.ts
+/**
+ * 弹性形变指针物理
+ *
+ * rdev/liquid-glass-react 的交互手感：指针靠近/进入玻璃时，
+ * 按指针相对中心的方向做方向性拉伸与弹性平移，远离时回落。
+ * 纯函数实现，供 DOM 事件层驱动。
+ */
+/**
+ * 弹性形变输入
+ */
+type ElasticityInput = {
+  /**
+   * 指针 x（容器坐标系）
+   */
+  pointerX: number;
+  /**
+   * 指针 y（容器坐标系）
+   */
+  pointerY: number;
+  /**
+   * 容器中心 x
+   */
+  centerX: number;
+  /**
+   * 容器中心 y
+   */
+  centerY: number;
+  /**
+   * 激活强度 0..1（指针进入激活区为 1，远离衰减为 0）
+   */
+  activation: number;
+  /**
+   * 弹性系数 0..1
+   */
+  elasticity: number;
+};
+/**
+ * 方向性拉伸结果
+ */
+type DirectionalScale = {
+  /**
+   * x 方向缩放
+   */
+  scaleX: number;
+  /**
+   * y 方向缩放
+   */
+  scaleY: number;
+};
+/**
+ * 弹性平移结果
+ */
+type ElasticTranslation = {
+  /**
+   * x 平移（px）
+   */
+  translateX: number;
+  /**
+   * y 平移（px）
+   */
+  translateY: number;
+};
+/**
+ * 计算方向性拉伸：指针方向轴压缩、垂直轴拉伸（凸透镜被推挤的观感）
+ *
+ * @param input - 弹性形变输入
+ * @returns 方向性缩放（1 = 无形变）
+ */
+declare function calculateDirectionalScale(input: ElasticityInput): DirectionalScale;
+/**
+ * 计算弹性平移：玻璃向指针方向轻微平移（被"拖拽"的观感）
+ *
+ * @param input - 弹性形变输入
+ * @returns 平移量（px）
+ */
+declare function calculateElasticTranslation(input: ElasticityInput): ElasticTranslation;
+/**
+ * 计算激活强度：激活区内为 1，区外按距离指数衰减
+ *
+ * @param pointerX - 指针 x
+ * @param pointerY - 指针 y
+ * @param centerX - 中心 x
+ * @param centerY - 中心 y
+ * @param radius - 激活半径（px）
+ * @returns 激活强度 0..1
+ */
+declare function calculateActivation(pointerX: number, pointerY: number, centerX: number, centerY: number, radius: number): number;
+//#endregion
+//#region src/support.utils.d.ts
+/**
+ * SVG filter 路线支持检测
+ *
+ * Firefox 下 SVG displacement filter 作用于 backdrop-filter 的行为不符合预期
+ * （rdev/liquid-glass-react 的已知兼容问题），返回不支持由装配层降级。
+ */
+/**
+ * 支持检测结果
+ */
+type SvgFilterSupport = {
+  /**
+   * 是否支持 SVG displacement 路线
+   */
+  supported: boolean;
+  /**
+   * 不支持原因（支持时为空字符串）
+   */
+  reason: string;
+};
+/**
+ * 检测当前环境对 SVG displacement 路线的支持
+ *
+ * @returns 支持检测结果
+ */
+declare function detectSvgFilterSupport(): SvgFilterSupport;
+//#endregion
+//#region src/svg-filter-renderer.utils.d.ts
+/**
+ * 渲染上下文（构造入参）
+ */
+type SvgFilterRendererContext = {
+  /**
+   * 初始参数
+   */
+  params: LiquidGlassParams;
+  /**
+   * 初始尺寸
+   */
+  size: LiquidGlassSize;
+};
+/**
+ * SVG filter 渲染器
+ */
+declare class SvgFilterRenderer implements LiquidGlassRenderer<HTMLElement> {
+  /**
+   * 后端标识
+   */
+  readonly backend: 'svg-filter';
+  /**
+   * 宿主元素（mount 后可用）
+   */
+  private host;
+  /**
+   * SVG defs 载体元素
+   */
+  private svgHost;
+  /**
+   * filter 元素 id
+   */
+  private filterId;
+  /**
+   * 当前参数
+   */
+  private params;
+  /**
+   * 当前尺寸
+   */
+  private size;
+  /**
+   * 构造渲染器
+   *
+   * @param context - 渲染上下文（初始参数与尺寸）
+   */
+  constructor(context: SvgFilterRendererContext);
+  /**
+   * 挂载到 DOM 元素
+   *
+   * @param target - 宿主元素
+   */
+  mount(target: HTMLElement): void;
+  /**
+   * 热更新参数（重建位移图与 filter）
+   *
+   * @param params - 完整参数
+   */
+  update(params: LiquidGlassParams): void;
+  /**
+   * 尺寸变化（重建位移图与 filter）
+   *
+   * @param size - 新尺寸
+   */
+  resize(size: LiquidGlassSize): void;
+  /**
+   * 获取能力描述
+   *
+   * @returns 能力描述
+   */
+  getCapabilities(): RendererCapability;
+  /**
+   * 卸载并释放资源（幂等）
+   */
+  unmount(): void;
+  /**
+   * 应用当前参数：重建位移图、filter 图与元素样式
+   */
+  private apply;
+}
+//#endregion
+//#region src/index.d.ts
+/**
+ * 命令式创建入口：在目标元素上挂载 SVG filter 玻璃效果
+ *
+ * @param element - 宿主元素
+ * @param input - 参数输入（预设 + 覆盖）
+ * @returns 渲染器实例（调用方持有并负责 unmount）
+ */
+declare function createLiquidGlass(element: HTMLElement, input?: LiquidGlassParamsInput): SvgFilterRenderer;
+//#endregion
+export { type DirectionalScale, type DisplacementMapResult, type ElasticTranslation, type ElasticityInput, type FilterGraphOptions, SvgFilterRenderer, type SvgFilterSupport, buildFilterMarkup, calculateActivation, calculateDirectionalScale, calculateElasticTranslation, createLiquidGlass, describeFilterChain, detectSvgFilterSupport, generateDisplacementMap };

package/dist/index.js

@@ -0,0 +1,3 @@
+import{channelDispersionScales as e,maxDisplacement as t,refractionDisplacement as n,resolveParams as r,sdShape as i,sdfOutwardNormal as a}from"@longzai-intelligence-liquid-glass/core";function o(e){if(typeof document>`u`)return null;let r=document.createElement(`canvas`),o=Math.max(e.width,e.height,1),s=Math.min(1,512/o),c=Math.max(2,Math.round(e.width*s)),l=Math.max(2,Math.round(e.height*s));r.width=c,r.height=l;let u=r.getContext(`2d`);if(u===null)return null;let d={kind:e.shape,width:e.width*s,height:e.height*s,radius:e.cornerRadius*s,smoothing:e.cornerSmoothing},f=(e,t)=>i(e,t,d),p={refraction:e.refraction,refractionHeight:e.refractionHeight*s,bevel:e.bevel,bevelExponent:e.bevelExponent,displacementScale:1},m=Math.max(t(p),1),h=u.createImageData(c,l);for(let e=0;e<l;e+=1)for(let t=0;t<c;t+=1){let r=t-c/2,i=e-l/2,o=f(r,i),s=n(o,a(f,r,i,1),p),u=(e*c+t)*4;h.data[u]=Math.round(Math.min(Math.max(.5+s.x/(2*m),0),1)*255),h.data[u+1]=Math.round(Math.min(Math.max(.5+s.y/(2*m),0),1)*255),h.data[u+2]=0,h.data[u+3]=255}return u.putImageData(h,0,0),{dataUrl:r.toDataURL(`image/png`),width:c,height:l,range:m}}function s(e){let t=[`1 0 0 0 0  0 0 0 0 0  0 0 0 0 0  0 0 0 1 0`,`0 0 0 0 0  1 0 0 0 0  0 0 0 0 0  0 0 0 1 0`,`0 0 0 0 0  0 0 0 0 0  1 0 0 0 0  0 0 0 1 0`];return t[e]??t[0]??`1 0 0 0 0  0 0 0 0 0  0 0 0 0 0  0 0 0 1 0`}function c(e,t){return`  <feDisplacementMap in="SourceGraphic" in2="map" scale="${t.toFixed(2)}" xChannelSelector="R" yChannelSelector="G" result="${e}"/>`}function l(t){let{filterId:n,map:r,params:i}=t,a=e(i.dispersion),o=r.range,l=i.blur>0?`  <feGaussianBlur stdDeviation="${(i.blur/2).toFixed(2)}" in="warped" result="softened"/>`:``,u;u=i.dispersion<=0?`${c(`warped`,o)}`:[c(`dispR`,o*a.r),`  <feColorMatrix in="dispR" type="matrix" values="${s(0)}" result="rOnly"/>`,c(`dispG`,o*a.g),`  <feColorMatrix in="dispG" type="matrix" values="${s(1)}" result="gOnly"/>`,c(`dispB`,o*a.b),`  <feColorMatrix in="dispB" type="matrix" values="${s(2)}" result="bOnly"/>`,`  <feBlend in="rOnly" in2="gOnly" mode="screen" result="rg"/>`,`  <feBlend in="rg" in2="bOnly" mode="screen" result="warped"/>`].join(`
+`);let d=i.blur>0?`softened`:`warped`;return[`<filter id="${n}" x="-20%" y="-20%" width="140%" height="140%" color-interpolation-filters="sRGB">`,`  <feImage href="${r.dataUrl}" result="map" x="0" y="0" width="${r.width}" height="${r.height}" preserveAspectRatio="none"/>`,u,l,`  <feMerge result="final"><feMergeNode in="${d}"/></feMerge>`,`</filter>`].filter(e=>e.length>0).join(`
+`)}function u(e){let t=[`feImage`];return e.dispersion<=0?t.push(`feDisplacementMap`):t.push(`feDisplacementMap`,`feColorMatrix`,`feDisplacementMap`,`feColorMatrix`,`feDisplacementMap`,`feColorMatrix`,`feBlend`,`feBlend`),e.blur>0&&t.push(`feGaussianBlur`),t}function d(e){let t=e.pointerX-e.centerX,n=e.pointerY-e.centerY,r=Math.hypot(t,n);if(r===0||e.elasticity===0)return{scaleX:1,scaleY:1};let i=t/r,a=n/r,o=e.elasticity*e.activation;return{scaleX:1-o*Math.abs(i)*.5,scaleY:1-o*Math.abs(a)*.5}}function f(e){let t=e.pointerX-e.centerX,n=e.pointerY-e.centerY,r=e.elasticity*e.activation;return{translateX:t*r*.15,translateY:n*r*.15}}function p(e,t,n,r,i){let a=Math.hypot(e-n,t-r);if(a<=i)return 1;let o=(a-i)/Math.max(i,1);return Math.max(Math.exp(-o*3),0)}function m(){return typeof window>`u`||typeof document>`u`?{supported:!1,reason:`SSR 或非浏览器环境`}:window.navigator.userAgent.toLowerCase().includes(`firefox`)?{supported:!1,reason:`Firefox 不支持 backdrop-filter 上的 SVG displacement`}:!(typeof CSS<`u`&&CSS.supports!==void 0)||CSS.supports(`backdrop-filter`,`blur(1px)`)||CSS.supports(`-webkit-backdrop-filter`,`blur(1px)`)?{supported:!0,reason:``}:{supported:!1,reason:`backdrop-filter 不受支持`}}var h=class{backend=`svg-filter`;host=null;svgHost=null;filterId=``;params;size;constructor(e){this.params=e.params,this.size=e.size}mount(e){this.host=e,this.filterId=`liquid-glass-${Math.random().toString(36).slice(2,10)}`,this.svgHost=document.createElementNS(`http://www.w3.org/2000/svg`,`svg`),this.svgHost.setAttribute(`class`,`liquid-glass-svg-filter-host`),this.svgHost.setAttribute(`width`,`0`),this.svgHost.setAttribute(`height`,`0`),this.svgHost.style.position=`absolute`,this.svgHost.style.pointerEvents=`none`,document.body.appendChild(this.svgHost),this.apply()}update(e){this.params=e,this.apply()}resize(e){this.size=e,this.apply()}getCapabilities(){return{backend:`svg-filter`,supportsRefraction:!0,supportsDispersion:!0,supportsBlur:!0,supportsSpecular:!0,supportsDomBackdrop:!0}}unmount(){this.svgHost!==null&&(this.svgHost.remove(),this.svgHost=null),this.host!==null&&(this.host.style.backdropFilter=``,this.host.style.background=``,this.host.style.boxShadow=``,this.host.style.borderRadius=``,this.host=null)}apply(){if(this.host===null||this.svgHost===null)return;let e=o(this.params);this.svgHost.innerHTML=``;let t=`blur(${this.params.blur}px) saturate(${this.params.saturation}) brightness(${this.params.brightness})`;if(e!==null){let n=document.createElementNS(`http://www.w3.org/2000/svg`,`svg`);n.innerHTML=l({filterId:this.filterId,map:e,params:this.params});let r=n.querySelector(`filter`);r!==null&&(this.svgHost.appendChild(r),t=`url(#${this.filterId}) ${t}`)}this.host.style.borderRadius=this.params.shape===`circle`?`50%`:`${this.params.cornerRadius}px`,this.host.style.backdropFilter=t,this.host.style.setProperty(`-webkit-backdrop-filter`,t),this.host.style.background=`rgba(${Math.round(this.params.tint.r*255)}, ${Math.round(this.params.tint.g*255)}, ${Math.round(this.params.tint.b*255)}, ${this.params.tint.a})`,this.host.style.boxShadow=`inset 1px 1px 0 rgba(255,255,255,${this.params.specular.toFixed(3)}), inset -1px -1px 0 rgba(255,255,255,${(this.params.specular*.5).toFixed(3)}), 0 8px 32px rgba(0,0,0,0.12)`}};function g(e,t){let n=r(t),i=e.getBoundingClientRect(),a=new h({params:n,size:{width:i.width>0?i.width:n.width,height:i.height>0?i.height:n.height}});return a.mount(e),a}export{h as SvgFilterRenderer,l as buildFilterMarkup,p as calculateActivation,d as calculateDirectionalScale,f as calculateElasticTranslation,g as createLiquidGlass,u as describeFilterChain,m as detectSvgFilterSupport,o as generateDisplacementMap};

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@longzai-intelligence-liquid-glass/svg-filter",
+  "version": "0.0.1",
+  "description": "Liquid Glass SVG feDisplacementMap 渲染后端",
+  "license": "UNLICENSED",
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "lzi-builder",
+    "build:prod": "NODE_ENV=production bun run build",
+    "prepublishOnly": "bun run build:prod",
+    "typecheck": "bun run typecheck:app && bun run typecheck:node && bun run typecheck:test",
+    "typecheck:app": "lzi-tsgo typecheck tsconfig/app.json",
+    "typecheck:node": "lzi-tsgo typecheck tsconfig/node.json",
+    "typecheck:test": "lzi-tsgo typecheck tsconfig/test.json",
+    "lint": "oxlint && oxfmt --check",
+    "lint:fix": "oxlint --fix && oxfmt",
+    "test": "lzi-bun-cli test",
+    "test:watch": "lzi-bun-cli test --watch",
+    "test:coverage": "lzi-bun-cli test --coverage",
+    "clean": "lzi-dev-cli clean"
+  },
+  "dependencies": {
+    "@longzai-intelligence-liquid-glass/core": "0.0.1"
+  },
+  "packageManager": "bun@1.3.14"
+}